@irwinproject/shapley v1.0.41

Shapley

Shapley is a component library which uses an svg layer to render components as non rectangular shapes.

Installation

npm install @irwinproject/shapley

How it works.

Shapley uses an svg as a background layer which references cached path commands to clip and portray components as a custom shape. To accomplish this a lightweight svg path command parser has been implemented and made available which is useful in building animated paths or dynamic renderings in real time.

Usage

Shape Component

The shape component can be used to reference cached shapes and to draw shapes on demand.

Props

import { Shape } from "@irwinproject/shapley";

export const MyComponent = () => {
	return (<Shape 
	className="diamond-styles" 
	as="h4" 
	d="M 0.5,0 1,0.5 0.5,1 0,0.5z">
		Hello World!
	<Shape>);
};

Glyph

A glyph is a component that allows a sort of canvas to draw with path commands.

Currently glyphs cant be cached.

Glyphs accept all the properties a <path> component accepts however d also accepts a D instance.

Additional Props

import { Glyph } from "@irwinproject/shapley";

export const MyGlyph = ()=>{
	return <Glyph d={D.rounded(0, [
		100,75, 0,-50, -50,-25, -50,25, 0,50, 100,50, 0,50, -50,25, -50,-25, 0,-50
	])}>
}

ShapeCache

A shape cache is a special (invisible) svg component which only contains cached shapes or paths available by reuse.

import { ShapeCache, D } from "@irwinproject/shapley";

export const MyCache = () => {
	return (<ShapeCache shapes={{
		hexagon: D.polygon(6, {rotation: 30}).toObjectBounding(),
		pentagon: D.polygon(5, {rotation: 90}).toObjectBounding(),
		diamond: D.polygon(4).toObjectBounding()
	}}>);
}

if a cached shape is going to be used as a background layer it is recommended the shape be converted to a objectBounding viewBox. (This allows the shape to scale with the bounds of the rectangle.)

import { Shape } from "@irwinproject/shapley";

export const Hexagon = () => {
	return (<Shape 
	sref="hexagon">
		Hello World
	</Shape>);
}

Shape Grids

Shape grids are simply css grids with some properties to help layout overlapping bounding recs more simply.

For a shape grid to work propely either both the grid-column-template and/or grid-row-template will need to be set. either by utilizing the cellColumns or the cellRows property. (the templates can also be applied directly using css).

The cellSize property is necessary as well. the first value being the number of columns a cell spans while the second is the number of rows a cell spans. (these can be applied directly with css using the grid-column-end and grid-row-end).

I provide a few layout functions that simplify laying out grids with regular polygons however custom layout functions can be made as well.

import { ShapleyGrid, HexagonLayout } from "@irwinproject/shapley";
const GridComponent = () => {
	return (<ShapleyGrid cellColumns="repeat(6, 1fr 2fr) 1fr" cellSize={[3,2]} layoutFN={HexagonLayout(6, 'hexagon')}>
		<ShapleyGridCell>
			{/*...*/}
		</ShapleyGridCell>
		{/* If a layout function is not provided the row, column and shape reference (sref) property can be set directly on the grid cell*/}
		<ShapleyGridCell row={2} column={3} sref="hexagon"></ShapleyGridCell>
	</ShapleyGrid>)
}

Layout functions

Layout functions are a way to describe a cell position based upon the index. This allows the cells bounding rects to overlap without statically providing cell positioning in css.

Each cell uses a shape to clip its bounding rect to ensure mouse events are triggered on the correct component.

type LayoutFN = (index: number) => ({
	row: number,
	column: number,
	sref?: string
})

Any functions complying to this pattern can be used to layout grid cells. the index value provided is the sequential index of the component being iterated.

Warning: The Shapley grid only inject these properties into children ShapleyGridCell.

Styling

The shape component can be styled like most other html elements with a few exceptions

• Do not use css borders CSS borders are always rectangular Instead utilize svg's stroke properties.
• Do not use Drop-shadow Currently using filter and backdrop-filter on a shapes parent object are the best method to add shadows to shapes. it may be possible to make custom effects such as <feDropShadow> that can be applied directly to a shape. I will explore this when time allows.

The recommended method to style a shape is via css or css-in-js.

CSS Variables.

### Classes

D

D is an attempt to make svg path commands a bit more useful in javascript.

D acts as a sort of lazy buffer which combines mutation operations to be performed the next time the path commands are requested for render.

D and all of its subsequent classes are convertable to a string which will result in a valid path command string.

for D to work as it should its backing store holds a IterableIterator (generator) instead of an array of points. this allows for multiple source of truth formats to be applicable. The simplest way to explain this is the source of truth can be anything your providing the instructions on how to traverse that source of truth.

This has two effects. generators can be combined to essencially enqueue modifications to occur in the next render cycle. Additionally, Path commands can be generated programmatically, via static string, or even with arbitrary types such as a flat array of numbers.

Some limitations include:

• Number of points within the buffer is unknown
• Points can only be iterated in order if reference to separate points is desired two iterations will be necessary to index the points.

I will be releasing more detailed documentation soon.

constructor

Typically a static method would be used to create a D instance. the constructor accepts multiple types.

arg: string | number[] | Command[] | ()=>Generator<Command>

• the initializer type.
• If a string is provided to first argument it will be parsed as a path command. The source of truth will be the string and each time its iterated.
• If a number array is provided the array will be iterated over by two concluding with a z command to close the shape.
• If a Command Generator is provided you have direct control over the PathCommand instances. (Currently these classes are experimental I will release more documentation soon.).

margin: number

This value will be applied to each side of the view box.

properties

methods

Static methods

D has a range of static methods to assist in initializing and creating various shapes. | Property | Return | Description | |:--------:|:----:|:-----------:| | parse(d: string) | Generator<Command> | parse a path command string to an instance of D. | | fromLines(d: number[]) | Generator<Command> | treats the array as a 2d vertex list of points. | | polygon(sides: number, options?: {}) | D | Generate a regular polygon of the provided number of sides. this method supportes decimal values in the side to assist with animation. | | polygon.options.radius | number = 1 | The circumradius of the polygon | | polygon.options.rotation | number = 0 | Degrees the object should be rotated by. | | center | x:number, y: number = 0,0 | The center point of the polygon. | | cornerRadius | number = 0 | The distance from the polygon's points at which rounding should begin. | | connectAll | boolean = false | Connecting all the points just creates an interesting effect so I figured why not. | | shape(cornerRadius: number, points: ()=>Generator(x: number, y: number) | number[]) | D | Creates a shape from an iterator of points or an Array. | | rounded(cornerRadius: number, d: readonly number[]) | D | Iterates of a vertex list and rounds each corner by the provided amount. | | fromCached(cache: DCacheItem) | D | recreate a D instance from a cache object. |