@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/board-places.mjs

@@ -0,0 +1,224 @@
+// Where the cards of a custom page's board go (notes/plans/custom-blocks-spec-2026-11-07.md §6, §8;
+// docs/render.md "A custom page"): the one set of rules every side places a card by, so that what the
+// page shows while a card is dragged, what the page service writes and what gallery page add writes
+// are the same. The page service (src/editor/page-service.mjs) and gallery page add place and push
+// cards in the file by them; the kit's board script (src/render/kit/board/) draws a board by them,
+// cards of `fit: "content"` as high as what they hold, those under them pushed down; the page's board
+// editing (src/editor/page/board/) shows a drag's spot and the cards it pushes by them before it asks
+// the service. Pure: no DOM, no Node.
+//
+// A card is { id, x, y, w, h } in whole cells of a board 12 columns wide, at most 24 cells high: what the
+// file says, wherever it is drawn. A cell's side is fixed (CELL), as a document's reading width is, so a
+// board is as wide whatever the window (the workbench's sidebar open or folded); where the room holds
+// fewer than twelve of them the board is drawn in as many as it holds (gridFor), 4 at the least, its
+// cards one after another in their order (flow), as wide as they are, which nothing writes: nothing is
+// placed there. Nothing here ever moves a card up: a card pushed down stays where it was pushed, the room
+// it left a room on the board, as on a board things are pinned to.
+
+/** The cells of a board's row, and the most a card is high (the manifest's own range, spec §1). */
+export const GRID = Object.freeze({ columns: 12, rows: 24 });
+
+/** The pixels between two cells. */
+export const GAP = 16;
+
+/**
+ * A cell's side in pixels, the same however wide the window (the user's word of 2026-11-09: the cards no
+ * larger with the sidebar folded, only further in): twelve of them and their gaps are 944px, which the
+ * workbench's content holds on a 1280px laptop with the sidebar open at its default width.
+ */
+export const CELL = 64;
+
+/** The fewest columns a board is drawn in: where not even these fit their cells are drawn smaller (a phone). */
+export const LEAST = 4;
+
+/** The pixels `n` cells take on a board whose cell is `cell` pixels (n cells and the n - 1 gaps between them). */
+export const spanOf = (n, cell, gap = GAP) => n * cell + Math.max(0, n - 1) * gap;
+
+/**
+ * A board drawn in `room` pixels: { columns, cell, width }, as many whole cells of CELL, GAP apart, as
+ * the room holds, from LEAST to 12; where not even LEAST fit, LEAST cells as large as the room lets
+ * them be. `width` is what its columns take (the board stands them in its middle).
+ */
+export function gridFor(room) {
+  const fit = Math.floor((Math.max(0, room) + GAP) / (CELL + GAP));
+  const columns = Math.max(LEAST, Math.min(GRID.columns, fit));
+  const cell = fit >= LEAST ? CELL : Math.max(0, (room - (LEAST - 1) * GAP) / LEAST);
+  return { columns, cell, width: spanOf(columns, cell) };
+}
+
+const whole = (value, fallback) => (Number.isInteger(value) ? value : fallback);
+
+/** Whether cards `a` and `b` share a cell. */
+export const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+
+/**
+ * Cells `{ x, y, w, h }` held to a board of `columns`: 1 <= w <= columns, 1 <= h <= 24, 0 <= x <=
+ * columns - w, 0 <= y; what is no whole number the default, a 4 x 2 card at 0, 0.
+ */
+export function onBoard({ x, y, w, h }, columns = GRID.columns) {
+  const width = Math.min(columns, Math.max(1, whole(w, 4)));
+  const height = Math.min(GRID.rows, Math.max(1, whole(h, 2)));
+  return { x: Math.min(columns - width, Math.max(0, whole(x, 0))), y: Math.max(0, whole(y, 0)), w: width, h: height };
+}
+
+/**
+ * The cards of a board with none sharing a cell, none moved up: `fixed` (ids) stay where they are,
+ * and every other card, in the order of its place (top to bottom, left to right, then as given), goes
+ * down until it shares no cell with one placed before it, right under the one it met. What the file
+ * says of a board that shares no cell is what this gives back. Returns new cards, in the order given.
+ * @template {{ id: string, x: number, y: number, w: number, h: number }} Card
+ * @param {Card[]} cards
+ * @param {Iterable<string>} fixed
+ * @returns {Card[]}
+ */
+export function settle(cards, fixed = []) {
+  const kept = new Set(fixed);
+  const placed = cards.filter((card) => kept.has(card.id)).map((card) => ({ ...card }));
+  const rest = cards.map((card, index) => ({ card, index })).filter(({ card }) => !kept.has(card.id))
+    .sort((a, b) => a.card.y - b.card.y || a.card.x - b.card.x || a.index - b.index);
+  for (const { card } of rest) {
+    const going = { ...card };
+    for (let met = placed.filter((other) => overlaps(going, other)); met.length > 0; met = placed.filter((other) => overlaps(going, other))) {
+      going.y = Math.max(...met.map((other) => other.y + other.h));
+    }
+    placed.push(going);
+  }
+  const at = new Map(placed.map((card) => [card.id, card]));
+  return cards.map((card) => at.get(card.id));
+}
+
+/**
+ * The cards with card `moved.id` at `moved`'s cells (held to the board), and those it now shares a cell
+ * with pushed down under it, and so on (settle): what a drop, a resize and a card put on a board at a
+ * place of its own do. A card of no id there joins them (a card added).
+ */
+export function pushDown(cards, moved, columns = GRID.columns) {
+  const cells = onBoard(moved, columns);
+  const next = cards.some((card) => card.id === moved.id)
+    ? cards.map((card) => (card.id === moved.id ? { ...card, ...cells } : card))
+    : [...cards, { ...moved, ...cells }];
+  return settle(next, [moved.id]);
+}
+
+/**
+ * The first place a card of `w` x `h` cells takes on a board holding `cards`, reading the board as a
+ * page is read: the topmost row it fits in, and there the leftmost column, sharing a cell with none.
+ * @returns {{ x: number, y: number }}
+ */
+export function freeSpot(cards, { w, h }, columns = GRID.columns) {
+  const { w: width, h: height } = onBoard({ x: 0, y: 0, w, h }, columns);
+  const bottom = cards.reduce((most, card) => Math.max(most, card.y + card.h), 0);
+  for (let y = 0; y <= bottom; y++) {
+    for (let x = 0; x + width <= columns; x++) {
+      if (!cards.some((card) => overlaps({ x, y, w: width, h: height }, card))) return { x, y };
+    }
+  }
+  return { x: 0, y: bottom };
+}
+
+/**
+ * The size a card of a block takes when it is put on a board (the manifest's `card`, as the catalog
+ * reads it: component-catalog.mjs cardOf): the first of its `sizes`, else its `w` and `h`; `h` null
+ * where the manifest says none, the fewest whole cells its content takes, which only the page measures
+ * (`measured`: 2 until then).
+ * @param {{ sizes?: number[][] | null, w?: number, h?: number | null } | null | undefined} card
+ * @returns {{ w: number, h: number, measured: boolean }}
+ */
+export function defaultSize(card) {
+  if (card?.sizes?.length) return { w: card.sizes[0][0], h: card.sizes[0][1], measured: false };
+  return { w: card?.w ?? 4, h: card?.h ?? 2, measured: card?.h === null || card?.h === undefined };
+}
+
+/** Of `sizes` ([w, h] each), the nearest to `w` x `h` (by the distance of their corners; the first of two as near). */
+export function nearestSize(sizes, { w, h }) {
+  let best = sizes[0];
+  let far = Infinity;
+  for (const size of sizes) {
+    const distance = (size[0] - w) ** 2 + (size[1] - h) ** 2;
+    if (distance < far) {
+      far = distance;
+      best = size;
+    }
+  }
+  return { w: best[0], h: best[1] };
+}
+
+/**
+ * What a card of a block may be resized to, for `w` x `h` asked: the nearest of the manifest's `sizes`
+ * where it lists them (unless `any`: a manifest that wrote a min or a max beside them frees the card,
+ * its sizes only the common ones its menu lists), else whole cells between its `min` and `max`
+ * (1 x 1 and 12 x 24 where it says none), never past the board.
+ */
+export function sizeFor(card, { w, h }, columns = GRID.columns) {
+  if (card?.sizes?.length && !card.any) {
+    const near = nearestSize(card.sizes, { w, h });
+    return { w: Math.min(columns, near.w), h: near.h };
+  }
+  const min = { w: card?.min?.w ?? 1, h: card?.min?.h ?? 1 };
+  const max = { w: Math.min(columns, card?.max?.w ?? GRID.columns), h: Math.min(GRID.rows, card?.max?.h ?? GRID.rows) };
+  return { w: Math.min(max.w, Math.max(min.w, Math.round(w))), h: Math.min(max.h, Math.max(min.h, Math.round(h))) };
+}
+
+/**
+ * The cells high a card of `fit: "content"` is drawn, for its content `height` in pixels (what it
+ * needs, its frame and padding with it) on a board whose cell is `cell` pixels: the spec's
+ * ceil((height + 16) / (cell + 16)), 1 at least and 24 at most.
+ */
+export function fitHeight(height, cell, gap = GAP) {
+  if (!(cell > 0)) return 1;
+  return Math.min(GRID.rows, Math.max(1, Math.ceil((height + gap) / (cell + gap) - 1e-6)));
+}
+
+/**
+ * The cards of a board drawn in `columns` fewer than twelve (a narrow room: gridFor): one after another
+ * in the order of their places (top to bottom, left to right, then as given), each as wide as it is but
+ * never wider than the row (`w` held to `columns`) and as high, each at the first spot at or after where
+ * the one before it ends, row by row, that shares no cell with those before it (as a grid flows its items
+ * with no place of their own: no card goes before one it came after, so a room may be left beside a tall
+ * one). What is drawn only, never written: the file's twelve-column places stay as they are, and the
+ * board is drawn by them again once the room holds twelve. Returns new cards, in the order given.
+ * @template {{ id: string, x: number, y: number, w: number, h: number }} Card
+ * @param {Card[]} cards
+ * @param {number} columns
+ * @returns {Card[]}
+ */
+export function flow(cards, columns) {
+  const order = cards.map((card, index) => ({ card, index })).sort((a, b) => a.card.y - b.card.y || a.card.x - b.card.x || a.index - b.index);
+  const placed = [];
+  const at = new Map();
+  let row = 0;
+  let column = 0;
+  for (const { card, index } of order) {
+    const w = Math.max(1, Math.min(card.w, columns));
+    let x = column;
+    let y = row;
+    for (;;) {
+      if (x + w > columns) {
+        x = 0;
+        y += 1;
+        continue;
+      }
+      const spot = { x, y, w, h: card.h };
+      if (!placed.some((other) => overlaps(spot, other))) break;
+      x += 1;
+    }
+    const going = { ...card, x, y, w };
+    placed.push(going);
+    at.set(index, going);
+    row = y;
+    column = x + w;
+  }
+  return cards.map((_, index) => at.get(index));
+}
+
+/** The whole cells `pixels` are nearest to, from a board's edge: what a drag snaps to. */
+export const cellAt = (pixels, cell, gap = GAP) => (cell > 0 ? Math.round(pixels / (cell + gap)) : 0);
+
+/** The cards whose cells changed from `before` to `after` (lists of cards), by id: [{ id, x, y, w, h }] as `after` has them. */
+export function moved(before, after) {
+  const was = new Map(before.map((card) => [card.id, card]));
+  return after.filter((card) => {
+    const old = was.get(card.id);
+    return !old || old.x !== card.x || old.y !== card.y || old.w !== card.w || old.h !== card.h;
+  });
+}

package/browser/shared/card-size.mjs

@@ -0,0 +1,59 @@
+// What a block's script is told of the custom page it stands on (notes/plans/custom-blocks-spec-2026-11-07.md,
+// sections 3, 5 and 6), as the kit's runtime reads it (runtime/kernel.js: context.place, context.size,
+// context.state): the page's markup, a card's id and the cells the board draws it at. The page's host
+// writes that markup and its board script lays the cards out by the rule below (the kit's board/
+// imports cellsOf from here, as DocBoard.cellsOf): one rule, so that a block lays out for the card as
+// drawn, never for the raw attributes. Pure, for the page.
+
+/** A custom page's root, around every card (page.html's main). */
+export const PAGE = "main.gallery-page";
+
+/** A board of a custom page, its cards its children; it says how many columns it has now (data-columns: 12, fewer where it is narrower). */
+export const BOARD = ".gallery-board";
+
+/** A card of a board, around one instance: the closest one to an instance, whatever its tag. */
+export const CARD = ".gallery-card";
+
+/** A card's id, unique in its page: what an instance's reading state goes by there. */
+export const CARD_ID = "data-card-id";
+
+/** The most cells a card is wide and high (the manifest's own range for a card, spec section 1). */
+export const MOST = Object.freeze({ w: 12, h: 24 });
+
+/** What a card whose cells are no number is drawn at. */
+const DEFAULT = Object.freeze({ x: 0, y: 0, w: 4, h: 2 });
+
+const whole = (value, fallback) => {
+  const number = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(number) ? number : fallback;
+};
+
+/**
+ * A card's cells as the board draws them: its data-x, data-y, data-w and data-h, each a whole number
+ * (parsed as an integer: "8.5" is 8), held to 1 <= w <= 12, 0 <= x <= 12 - w, 0 <= y and
+ * 1 <= h <= 24, one that is no number the default (a 4 x 2 card at 0, 0).
+ * @param {{ dataset: Record<string, string | undefined> }} card
+ */
+export function cellsOf(card) {
+  const w = Math.min(MOST.w, Math.max(1, whole(card.dataset.w, DEFAULT.w)));
+  const h = Math.min(MOST.h, Math.max(1, whole(card.dataset.h, DEFAULT.h)));
+  const x = Math.min(MOST.w - w, Math.max(0, whole(card.dataset.x, DEFAULT.x)));
+  const y = Math.max(0, whole(card.dataset.y, DEFAULT.y));
+  return { x, y, w, h };
+}
+
+/**
+ * The cells a card is drawn at now, what context.size says: its cells (cellsOf), its width no more than
+ * the columns its board has now (data-columns, the board script's: 12, or fewer on a board narrower than
+ * twelve of its fixed cells, 4 at the least; 12 where it says none), its height the one the board
+ * script drew it at (--gallery-h: a card whose block lays out by its content is as high as that,
+ * whatever data-h says), else its own.
+ * @param {Element & { dataset: Record<string, string | undefined>, style?: CSSStyleDeclaration }} card
+ * @returns {{ w: number, h: number }}
+ */
+export function drawnCells(card) {
+  const { w, h } = cellsOf(card);
+  const columns = Number(/** @type {HTMLElement | null} */ (card.closest(BOARD))?.dataset.columns) || MOST.w;
+  const drawn = Number.parseInt(card.style?.getPropertyValue?.("--gallery-h") ?? "", 10);
+  return { w: Math.min(w, columns), h: Number.isFinite(drawn) ? Math.min(MOST.h, Math.max(1, drawn)) : h };
+}

package/browser/shared/colors.mjs

@@ -26,5 +26,6 @@ export const COLORS = [
 
 export const COLOR_NAMES = COLORS.map(({ name }) => name);
 
-/** The page's own text color and background (tokens.css --doc-text, --doc-surface) as [light, dark]: what no color is. */
-export const BODY = { text: ["#2c2c2b", "#f3f3f3"], background: ["#ffffff", "#202020"] };
+/** The page's own text color and background (tokens.css --doc-text, --doc-surface) as [light, dark]: what no color is. The text's light is
+ *  the kit's default; on an Apple platform it is #262626 (tokens.css, data-doc-platform), a shade a pasted color never needs to tell apart. */
+export const BODY = { text: ["#2d2d2d", "#f3f3f3"], background: ["#ffffff", "#202020"] };