@selimssevgi/cube-design-angular 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# changelog
+
+## 0.2.0
+
+- `cubeHold` (`CubeHold`, `CubeHeld`, `CUBE_HOLD_MS`, `CUBE_HOLD_SLOP`): pressing and holding a piece, the gesture cubes (tiles and the cube on top) and anlat (level tiles) each wrote by hand. a long press, a right click or the menu key raise one `cubeHeld`; a pinch or a drag never do; the click after a hold is swallowed. its hold time is 520 ms (cubes'), and each app may set its own (`cubeHoldMs`, anlat's is 480). what a hold opens stays in each app.
+- `cube-icon` (`CubeIcon`, `CubeIconName`, `CUBE_ICON_NAMES`, `cubeIconCells`): the icon on a tile of a cube the app keeps (a context cube and its parts), moved from cubes (`shared/icon.component.ts`, `app-icon`), plus Cubes' `plus` from its tiles. `<cube-icon [icon] [inUse]>`; a view's icon (`square`, `one` … `four`, `grid-4x5`, `grid-3x6`) is the cells of its own shape. its look comes from `--cube-icon-size`, `--cube-icon-stroke`, `--cube-icon-stroke-width`, `--cube-icon-cell-opacity` and `--cube-icon-in-use`, now set in both token files.
+- the context cube's model (`lib/context-cube/`), pure typescript, no components yet. its shape: `ContextPartKey` (names, change, view, sort, move, whose, hide, and any part an app adds), `CONTEXT_PART_ORDER` and `orderParts` (cubes' rows: how it is called, how it is shown, what i do with it), `ContextTile`, `ContextPath`, `ContextPick`. the contract an app fills from its own data, `ContextCubeSource<T>` (`parts`, `level`, `pick`, sync or a promise), and its words, `ContextWords`; both through the tokens `CONTEXT_CUBE_SOURCE` and `CONTEXT_CUBE_WORDS`. the package ships no words.
+- the levels every app shares, as pure functions: `partsLevel` (its top), `namesLevel` (every name with its day and hands, the one in use first, a plus when the app allows), `hideLevel` (shown, hidden), `viewLevel`, `sortLevel` and `sortDirectionsLevel` (the options, the one in use, two directions).
+- `<cube-context [held] [path]>` (`CubeContext`): one level of a context cube drawn as a complete square of icon tiles, as cubes' own cube draws it (`app-tiles` with icons, `levelFor`): quiet solid outlines for open places (dashed where a plus can add), the one in use marked and, when the app gives `ContextWords.inUse`, said, the words shrinking as the square fills. a tap asks the source's `pick` and comes out as `(enter)` (a path), `(done)` (the tile) or `(out)`; `stay` draws the level again; every tile waits while a promise is answered, and a late answer for a level already left is dropped. it never routes, zooms, draws a head or says a word. `[source]` and `[words]` override the tokens for one screen. also `contextIcon`, `contextSquare`, `contextLevelFor` and the `--cube-context-*` variables in both token files.
+- `<cube-context>` says `(tapped)` (`ContextTapped`: the tile and its element) before the source answers, so an app grows the next level out of the tapped tile, as cubes does with every zoom. found trying it in cubes.
+- `<cube-context>`'s own classes start with `cc-` (`cc-square`, `cc-tile`, `cc-place`, `cc-icon`, `cc-t`, `cc-m`, `cc-tick`, `cc-l0`…`cc-l4`, `cc-in-use`, `cc-pale`, `cc-adds`, `cc-busy`): cubes' global `.tile .icon`, `.place` and `.square.l2 .tile` rules reached inside it (emulated encapsulation only keeps rules in, not out). found trying it in cubes.
+- `partsLevel` draws hide as `shown` when the app gives no `now.hide.icon` (`PART_ICONS`): `cube-icon` has no `hide` icon.
+- from cubes' `core/world/arrange.ts`: `ViewKey`, `VIEW_KEYS`, `isView`, `Grid`, `gridFor` as they are, `Direction`, and a generic `sortItems(items, by, dir)` where what is not known yet comes last both ways.
+- `<cube-square [tiles] [view]>` (`CubeSquare`, `CubeSquareTile`): the square, the complete grid of tiles every face is drawn with, which mosaic (`app-square-tiles`), cubes (`app-tiles`) and the context cube each wrote. it places the tiles an app gives through `<ng-template cubeSquareTile let-tile let-level="level">` (also `index`, `cell`, `rowHeight`, `list`) in any view (`gridFor`), measures its own width (up to the window's height less 48 px for the square, at most `maxSide`, 880), and zooms a step when it has to hold more. open places only finish the last row (decision of 2026-11-01: three pieces in 4 × 5 are one row of four); the square keeps its n × n; one across is a list (`listRow`, 76 px). `[dashed]` dashes the open places where something could come; `[keyOf]` keeps a tile the same tile. no words, no tile drawing, no turning yet (turning rows come on top of it, off by default). also `squareLayout`, `squareLevelFor`, `squareGap`, `SquareLayout`, `SquareLevel`, `SquareRoom`, `SQUARE_MAX_SIDE`, `SQUARE_LIST_ROW`, and the `--cube-square-*` variables (`place`, `place-dashed`, `place-width`, `radius`, `gap-scale`) in both token files.
+- `contextLevelFor` and `ContextLevel` are now the square's `squareLevelFor` and `SquareLevel`, kept under their first names; `<cube-context>` is unchanged.
+- `turningRows(pieces, own, cols, rows)` (`TurningRows`, `TURNING_SIDES`): the layout of turning rows (selim: row rotation), moved from mosaic (`shared/cube/turning-rows.ts`, the todarch cube) and generalised from a 3 × 3 front to cols × rows, so cubes' fixed grids (4 × 5, 3 × 6) can turn once full. pure, no angular. the front stays full, the own box keeps its last place, the rest fills row one's other three sides then row two's; past four sides a row, rows are added. with only `cols` it gives mosaic's answer. one fix on the way: a piece that is falsy (a `0`) now counts as something on its side. the square that draws and turns it is not in yet.
+- `<cube-square [turning]>`: turning rows on the square, off by default (`turning`, `turnBelow` 640, `across` 3, `isOwn`, `nudgeKey`; `turningFront`, `TURNING_BELOW`, `TURNING_NUDGE_UNTIL`). on a phone, a square or fixed grid holding more than its front keeps its size and each row turns like a puzzle cube's layer, as in mosaic's todarch cube: a sideways drag settles on a side and passes empty ones, the edge of the next side and a nudge until three turns, `inert` sides not facing. new on the way in: the arrow keys on a focused row turn it and move the focus along (a keyboard reaches every piece), a second finger lets the turn go (a pinch), and reduced motion stops the nudge. `--cube-square-edge` and `--cube-square-focus` in both token files.
+- `<cube-context>` draws its square with `<cube-square>` instead of its own, so the package keeps one square: the same layout, size, zoom and open places (dashed where a plus can add, `cs-dashed`), its tiles unchanged. its square and places are now `cs-square` and `cs-place`; `cc-square` and `cc-place` are gone, and the level classes sit on each tile (`cc-tile cc-l2`). `contextSquare` and `contextLevelFor` stay.
+
+## 0.1.0
+
+- `drawCube`, `sizeFor` and their types: the isometric cube of small cubes, moved from cubes (`core/drawing/cube-drawing.ts`), the same file mosaic copied.
+- `cube-picture` (`CubePicture`): the cube picture, its look from css variables; `tokens/light.css` (cubes, anlat) and `tokens/dark.css` (mosaic) set them.

package/README.md

@@ -1,3 +1,424 @@
-# Temporary Holding Version
+# @selimssevgi/cube-design-angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+cube design in angular. cube design is a way of looking where a piece sits on several groupings at
+once and every piece can open as a cube of its own (https://cube-design.selimssevgi.com). this
+package holds the pieces of it that anlat, mosaic and cubes found the same answer for, so a
+solution found in one app is used by all.
+
+it holds only what has settled. what is still being discovered stays in each app until two apps use
+it and its cube design decision is kept; then it moves in here.
+
+## install
+
+```shell
+npm install @selimssevgi/cube-design-angular@0.2.0 --save-exact
+```
+
+pin the exact version: a new version changes nothing in an app until that app takes it in its own
+PR. it needs angular 22.
+
+## the cube picture
+
+```ts
+import { CubePicture } from '@selimssevgi/cube-design-angular';
+
+@Component({
+  imports: [CubePicture],
+  template: `<cube-picture [count]="8" [colours]="colours()" [width]="96" [hint]="true" />`,
+})
+```
+
+| input     | what it is                                                                    |
+| --------- | ----------------------------------------------------------------------------- |
+| `count`   | how many pieces; the cube is the smallest n × n × n that holds them (up to 7) |
+| `colours` | the stickers' colours in order; `null` is a sticker not known yet, drawn pale |
+| `width`   | the width in pixels (64)                                                      |
+| `hint`    | while small, the bigger cube it can grow into, faint and dashed               |
+| `whole`   | one colour on every sticker, as a value is drawn                              |
+| `rot`     | how many times it was turned; shifts the colours round                        |
+
+its look comes from css variables, so each app keeps its own dialect. without any it draws in the
+light dialect. add one of the two files to the app's global styles (`angular.json` › `styles`):
+
+```json
+"styles": ["node_modules/@selimssevgi/cube-design-angular/tokens/dark.css", "src/styles.css"]
+```
+
+or set the variables yourself: `--cube-top`, `--cube-left`, `--cube-right`, `--cube-edge`,
+`--cube-edge-width`, `--cube-sticker-edge`, `--cube-unknown`, `--cube-unknown-edge`, `--cube-hint`,
+`--cube-hint-opacity`. a dark mode is the same variables set again under
+`@media (prefers-color-scheme: dark)`.
+
+## the hold
+
+pressing and holding a piece is how it is acted on (principle 31). `cubeHold` is that gesture and
+nothing more: what the hold opens stays in the app.
+
+```ts
+import { CubeHold, CubeHeld } from '@selimssevgi/cube-design-angular';
+
+@Component({
+  imports: [CubeHold],
+  template: `<button cubeHold (cubeHeld)="own($event)" (click)="open()">…</button>`,
+})
+export class Tile {
+  own(held: CubeHeld) {
+    // held.via is 'press' or 'menu'; held.element is the button, for an own cube to grow out of
+  }
+}
+```
+
+| input              | what it is                                                           |
+| ------------------ | -------------------------------------------------------------------- |
+| `cubeHoldDisabled` | no hold at all; the browser keeps its own menu (`false`)             |
+| `cubeHoldMs`       | how long a press is held before it is a hold, in ms (`520`)          |
+| `cubeHoldSlop`     | how far the press may move before it is a drag instead, in px (`10`) |
+| `cubeHoldBuzz`     | a short buzz, `navigator.vibrate(12)`, when it holds (`true`)        |
+
+`cubeHeld` gives `{ via: 'press' | 'menu', element, event }`.
+
+- a press with a finger, a pen or the main mouse button that stays within the slop for the hold
+  time is a hold. a second finger (a pinch), a drag past the slop, letting go, a cancel or leaving
+  the element end the press without one.
+- a `contextmenu` (a right click, a phone's own long press, the menu key, shift+f10) holds at once
+  and keeps the browser's menu away. when a long press already held, the phone's contextmenu after
+  it does not hold a second time.
+- the one click that follows a hold is swallowed, so the piece does not also open. a tap still
+  opens it.
+- it never stops or prevents the pointer events, so a swipe or a pinch on the same element keeps
+  working.
+- on its element it sets `user-select: none` and `-webkit-touch-callout: none`, so no selection or
+  callout gets in the way; no other styles.
+
+## the context cube's model
+
+behind every piece sits a second cube, the app's, where it keeps how the piece is named, shown and
+kept; pressing and holding a piece walks into it (principle 31; cubes calls it the own cube). the
+package holds its shape, the app fills it:
+
+```ts
+import {
+  CONTEXT_CUBE_SOURCE,
+  CONTEXT_CUBE_WORDS,
+  ContextCubeSource,
+  hideLevel,
+  namesLevel,
+  partsLevel,
+} from '@selimssevgi/cube-design-angular';
+
+const todos: ContextCubeSource<Todo> = {
+  parts: (t) => ['names', 'hide'],
+  level: (t, path) =>
+    path.length === 0
+      ? partsLevel(['names', 'hide'], words)
+      : path[0] === 'names'
+        ? namesLevel(t.names, words, { canAdd: true })
+        : path[0] === 'hide'
+          ? hideLevel(t.hidden, words)
+          : null,
+  pick: async (t, path, tile) =>
+    path.length === 0 ? { kind: 'enter', path: [tile.key] } : { kind: 'done' },
+};
+
+providers: [
+  { provide: CONTEXT_CUBE_SOURCE, useValue: todos },
+  { provide: CONTEXT_CUBE_WORDS, useValue: words }, // every title and line, in the app's language
+];
+```
+
+the shared levels are `partsLevel`, `namesLevel`, `hideLevel`, `viewLevel`, `sortLevel` and
+`sortDirectionsLevel`; each tile's `data` says what it stands for, so `pick` reads it from there.
+`gridFor(view, count)` lays out a level or a cube, and `sortItems(items, by, dir)` orders items with
+what is not known yet last both ways. `<cube-context>` draws a level (below).
+
+## the context cube
+
+`<cube-context [held] [path]>` draws one level of the held thing's context cube as a complete square
+(`gridFor('square', n)`): an icon on every tile, the one in use marked, open places outlined, and
+the words shrinking as the square fills. a tap asks the source's `pick`; its answer comes out as
+`(enter)` with a deeper path, `(done)` with the tile used, or `(out)`; `stay` draws the level again
+where it is. a path the source has no level for (null) is `(out)` too.
+
+`(tapped)` comes first, with the tile and the element it is drawn in, before the source answers:
+keep the element, and grow the next level out of it (or whatever the pick opens, such as a copy
+made mine), as the app zooms into any other piece. cubes keeps it on its source.
+
+it never routes, zooms, draws a head or says a word of its own. the app hosts it in its own route,
+under its own head, and keeps the path in its url, so zooming out and the back button are the app's.
+a whole example, a to-do app with names and hide:
+
+```ts
+// todo-context.ts: the app's source and words
+import {
+  CONTEXT_CUBE_SOURCE,
+  CONTEXT_CUBE_WORDS,
+  ContextCubeSource,
+  ContextWords,
+  NamesData,
+  hideLevel,
+  namesLevel,
+  partsLevel,
+} from '@selimssevgi/cube-design-angular';
+
+export const TODO_WORDS: ContextWords = {
+  parts: {
+    names: { title: 'names', line: 'every name it has had' },
+    hide: { title: 'hide', line: 'in sight or out of it' },
+  },
+  views: {},
+  directions: { up: { title: 'first first' }, down: { title: 'last first' } },
+  hide: {
+    shown: { title: 'shown', line: 'among the others' },
+    hidden: { title: 'hidden', line: 'folded away' },
+  },
+  names: { another: { title: 'another name' }, line: (n) => (n.on ? `since ${n.on}` : null) },
+  inUse: 'in use',
+};
+
+export function todoContext(todos: TodoStore): ContextCubeSource<Todo> {
+  return {
+    parts: () => ['names', 'hide'],
+    level: (t, path) => {
+      switch (path[0]) {
+        case undefined:
+          // hide's tile shows what it holds now; without it, it shows `shown`.
+          return partsLevel(['names', 'hide'], TODO_WORDS, {
+            names: { line: t.name },
+            hide: { line: t.hidden ? 'hidden' : 'shown', icon: t.hidden ? 'hidden' : 'shown' },
+          });
+        case 'names':
+          return namesLevel(t.names, TODO_WORDS, { canAdd: true });
+        case 'hide':
+          return hideLevel(t.hidden, TODO_WORDS);
+        default:
+          return null;
+      }
+    },
+    pick: async (t, path, tile) => {
+      if (path.length === 0) return { kind: 'enter', path: [tile.key] };
+      if (path[0] === 'hide') {
+        await todos.hide(t.id, tile.data as boolean);
+        return { kind: 'done' };
+      }
+      const d = tile.data as NamesData;
+      if ('another' in d) return { kind: 'stay' }; // the app opens its own sheet to ask for it
+      await todos.rename(t.id, d.name.name);
+      return { kind: 'done' };
+    },
+  };
+}
+
+export const TODO_CONTEXT_PROVIDERS = [
+  { provide: CONTEXT_CUBE_SOURCE, useFactory: () => todoContext(inject(TodoStore)) },
+  { provide: CONTEXT_CUBE_WORDS, useValue: TODO_WORDS },
+];
+```
+
+```ts
+// the route that hosts it: /todo/:id/context and /todo/:id/context/:part
+{ path: 'todo/:id/context/:part', component: TodoContextScreen, providers: TODO_CONTEXT_PROVIDERS },
+{ path: 'todo/:id/context', component: TodoContextScreen, providers: TODO_CONTEXT_PROVIDERS },
+
+@Component({
+  imports: [CubeContext, AppHead],
+  template: `
+    @if (todo(); as t) {
+      <app-head [title]="t.name" (out)="back()" />
+      <cube-context
+        [held]="t"
+        [path]="path()"
+        (enter)="go($event)"
+        (out)="back()"
+        (done)="router.navigate(['/todo', t.id])"
+      />
+    }
+  `,
+})
+export class TodoContextScreen {
+  readonly id = input.required<string>();
+  readonly part = input<string>();
+  protected readonly router = inject(Router);
+  protected readonly todo = inject(TodoStore).byId(this.id); // a signal
+  protected readonly path = computed(() => (this.part() ? [this.part()!] : []));
+  protected go(path: string[]) {
+    this.router.navigate(['/todo', this.id(), 'context', ...path]);
+  }
+  protected back() {
+    this.router.navigate(this.part() ? ['/todo', this.id(), 'context'] : ['/todo', this.id()]);
+  }
+}
+```
+
+```html
+<!-- a tile of the list: a tap opens the to-do, a hold walks into its context cube -->
+<button
+  cubeHold
+  (cubeHeld)="router.navigate(['/todo', t.id, 'context'])"
+  (click)="router.navigate(['/todo', t.id])"
+>
+  {{ t.name }}
+</button>
+```
+
+a screen that holds a different source or other words passes `[source]` and `[words]` instead of
+the tokens. `[maxSide]` (880) caps the square on a wide screen; on a phone it is the host's width,
+and never taller than the window less 48px. `level` is read inside a computed, so a source that
+reads signals redraws by itself; one that does not is read again after every pick.
+
+the tile's icon is its `icon` when `cube-icon` draws it (`contextIcon`); `hide` draws `shown`, a
+tile that adds draws the plus, and an icon of the app's own draws a face. its look is the
+`--cube-context-*` variables, set in both token files: `-tile`, `-line`, `-ink`, `-quiet`,
+`-in-use`, `-adds`, `-adds-bg`, `-adds-ink`, `-focus` and `-radius`, with the `--cube-icon-*` ones
+for the icons. its square is `<cube-square>` (below), so it lays out, measures and zooms like every
+other face; its open places take the context cube's line and radius. `contextSquare(count, room)`
+and `contextLevelFor(cell)` are kept as plain functions.
+
+its own classes all start with `cc-` (`cc-tile`, `cc-icon`, …) and the square's with `cs-`, so an
+app's global `.tile`, `.square` or `.place` rules do not reach inside; style it through the
+variables only.
+
+## the square
+
+every face of a cube is drawn as a complete square of tiles (decision 23). `<cube-square>` is that
+square and nothing more: it places the tiles an app gives, and the app keeps drawing each tile.
+
+```ts
+import { CubeSquare, CubeSquareTile } from '@selimssevgi/cube-design-angular';
+
+@Component({
+  imports: [CubeSquare, CubeSquareTile],
+  template: `
+    <cube-square [tiles]="pieces()" [view]="view()" [keyOf]="byId">
+      <ng-template [cubeSquareTile]="pieces()" let-piece let-level="level" let-cell="cell">
+        <app-piece-tile [piece]="piece" [level]="level" [picture]="cell * 0.4" />
+      </ng-template>
+    </cube-square>
+  `,
+})
+export class Face {
+  byId = (p: Piece) => p.id;
+}
+```
+
+| input     | what it is                                                                          |
+| --------- | ----------------------------------------------------------------------------------- |
+| `tiles`   | the tiles, in the order they are placed                                             |
+| `view`    | a `ViewKey`: `square` (the default), `one` … `four` across, `grid-4x5`, `grid-3x6`  |
+| `maxSide` | the largest side it takes on a wide screen, in px (`880`)                           |
+| `listRow` | a row's height in one across, the list, in px (`76`)                                |
+| `dashed`  | open places dashed: something could come here (a cube of mine, a level with a plus) |
+| `keyOf`   | what keeps a tile the same tile across changes (its place by default)               |
+| `turning` | turning rows, off by default (below)                                                |
+
+the template is given the tile (`let-tile`), its `index`, its `level` (0, everything, to 4, only its
+icon or small cube; cubes' steps, `squareLevelFor`), its `cell` and `rowHeight` in px, and `list`
+in one across. a tile fills its cell; give it `height: 100%` or `display: grid` if it is a button.
+
+- the square view is the smallest n × n that holds the tiles, as wide as the host and at most the
+  window's height less 48 px, so it is seen whole. the other views are as long as they need and the
+  page scrolls.
+- open places only finish the last row; a view never draws a whole empty row (decision of
+  2026-11-01): three pieces in 4 × 5 are one row of four. the square keeps its n × n.
+- when it has to hold more it zooms out a step (not when the phone asks for less motion).
+- it says no word and draws no tile, so each app keeps its own pictures, tones, hold and hide.
+  `squareLayout(view, count, room)` is the same layout as a pure function.
+
+its look is css variables, set in both token files: `--cube-square-place` (an open place's
+outline), `--cube-square-place-dashed`, `--cube-square-place-width` (1.5px), `--cube-square-radius`
+(20px, closer as the square fills) and `--cube-square-gap-scale` (1; the gap itself follows the
+square, 12 px for 2 × 2 down to 5 px from 5 × 5).
+
+### turning rows on the square
+
+```html
+<cube-square
+  [tiles]="pieces()"
+  [turning]="rowsTurn()"
+  [isOwn]="isOwn"
+  nudgeKey="mosaic.turning-rows.turned"
+>
+  …
+</cube-square>
+```
+
+with `turning` on, a square or a fixed grid (4 × 5, 3 × 6) holding more than its front keeps its
+size on a phone and turns its rows instead (the layout is `turningRows`, below). each row is a band
+of four sides; a sideways drag on a row turns it and it settles on a side, never between two,
+passing the sides with nothing on them. the views of rows across (`one` … `four`) never turn, and a
+screen as wide as `turnBelow` (640 px) shows the whole square.
+
+| input       | what it is                                                                           |
+| ----------- | ------------------------------------------------------------------------------------ |
+| `turning`   | off (`false`) unless the app turns it on; each app gives the person its own switch   |
+| `turnBelow` | rows turn only on a screen narrower than this, in px (`640`)                         |
+| `across`    | the square's front while it turns: `across` × `across` (`3`)                         |
+| `isOwn`     | which tile is my own box: it keeps the front's last place, always seen               |
+| `nudgeKey`  | where the turns are counted on this phone (`localStorage`); none counts on this page |
+
+- a row with more shows the edge of its next side, and until three turns were counted it nudges
+  (turns a little and back) when the square opens; not when the phone asks for less motion.
+- the arrow keys on a focused row (or a tile in it) turn it, and the focus moves to the same place
+  on the side now facing, so a keyboard reaches every piece. the sides not facing are `inert` and
+  hidden from screen readers.
+- only one finger turns, and only sideways: up and down is the page scrolling, and a second finger
+  is a pinch (the row goes back to where it was). a turn lets go of a `cubeHold` on its tile, and the
+  tap that ends a turn is swallowed.
+- the edge's colour is `--cube-square-edge`, a focused row's outline `--cube-square-focus`.
+
+## the drawing alone
+
+`drawCube(count, colours, width, { hint, whole, rot })` returns the polygons as svg points, and
+`sizeFor(count)` the side of the smallest cube that holds `count`. they are plain functions, for a
+canvas or a picture of your own.
+
+## the icons
+
+```ts
+import { CubeIcon } from '@selimssevgi/cube-design-angular';
+
+@Component({
+  imports: [CubeIcon],
+  template: `<cube-icon [icon]="'sort'" [inUse]="false" />`,
+})
+```
+
+a tile of a cube the app keeps (a context cube and its parts) holds no pieces, so it shows an icon of
+what it is about instead of a small cube. `icon` is a `CubeIconName`: `names`, `name`, `change`,
+`move`, `place`, `whose`, `library`, `mine`, `shown`, `hidden`, `view`, `sort`, `kept`, `face`,
+`added`, `up`, `down`, `plus` (keeps something new beside the others), and the views `square`, `one`, `two`, `three`, `four`, `grid-4x5`,
+`grid-3x6`, each drawn as the cells of its own shape. `inUse` marks the one in use among its
+siblings. `CUBE_ICON_NAMES` lists them all.
+
+it says nothing; the tile's words come from the app. its look is css variables, set in both token
+files: `--cube-icon-size` (34px), `--cube-icon-stroke`, `--cube-icon-stroke-width`,
+`--cube-icon-cell-opacity`, `--cube-icon-in-use`. set `--cube-icon-size` on a tile to make it
+smaller or bigger.
+
+## turning rows (the layout)
+
+```ts
+import { turningRows } from '@selimssevgi/cube-design-angular';
+
+const { rows, sides } = turningRows(pieces, own, 4, 5);
+```
+
+turning rows (selim says row rotation) are an option of a view, first tried in mosaic's todarch
+cube: a square holding more pieces than its front keeps its front full and turns its rows like the
+layers of a puzzle cube. this is only the layout, a pure function with no angular: `rows[r][s][c]`
+is the piece on side `s` of row `r` at place `c` (side 0 is the front, null an open place), and
+`sides[r]` is how many sides of that row hold something (1: it does not turn).
+
+the front is `cols` × `rows` (3 × 3 when only `cols` is given, 4 × 5 and 3 × 6 for fixed grids).
+`own`, when not null, keeps the front's last place so it is always seen. the pieces past the front
+fill row one's three other sides, then row two's, so the open places gather at the very end; when
+four sides a row are not enough, rows are added below. `<cube-square [turning]>` draws and turns
+it (above).
+
+## rules this package keeps
+
+- no words: it never says anything to a person. every line comes from the app, in the app's language.
+- no tailwind classes: tailwind only builds the classes it finds in an app's own code, so they would
+  do nothing here. plain css and variables.
+- the code's words (cube, piece, kind, value, placement); each app keeps its own on screen.
+
+what changed in each version is in `CHANGELOG.md`.