@ankhorage/zora 25.2.1 → 25.3.0

package/src/features/grid-rulers/application/resolveGridRulerMarks.test.ts

@@ -0,0 +1,90 @@
+import { type GridViewport, snapWorldCoordinate } from '@ankhorage/grid-view';
+import { describe, expect, test } from 'bun:test';
+
+import { resolveGridRulerMarks } from './resolveGridRulerMarks';
+
+const viewport: GridViewport = {
+  width: 300,
+  height: 160,
+  offsetX: 40,
+  offsetY: 20,
+  pixelsPerUnitX: 2,
+  pixelsPerUnitY: 4,
+};
+
+describe('resolveGridRulerMarks', () => {
+  test('aligns independent axis scales and scroll offsets through the published viewport transform', () => {
+    expect(
+      resolveGridRulerMarks(viewport, 'x', {
+        kind: 'ticks',
+        specification: { mode: 'fixed', step: 20 },
+      }).map((mark) => mark.position),
+    ).toEqual([0, 40, 80, 120, 160, 200, 240, 280]);
+    expect(
+      resolveGridRulerMarks(viewport, 'y', {
+        kind: 'ticks',
+        specification: { mode: 'fixed', step: 10 },
+      }).map((mark) => mark.position),
+    ).toEqual([0, 40, 80, 120, 160]);
+  });
+
+  test('projects only visible variable-width category starts', () => {
+    expect(
+      resolveGridRulerMarks(viewport, 'x', {
+        kind: 'categories',
+        categories: [
+          { id: 'before', size: 10, start: 20 },
+          { id: 'visible-a', size: 37, start: 40 },
+          { id: 'visible-b', size: 91, start: 77 },
+        ],
+      }),
+    ).toEqual([
+      { categoryId: 'visible-a', level: 'major', position: 0 },
+      { categoryId: 'visible-b', level: 'major', position: 74 },
+    ]);
+  });
+
+  test('keeps a fixed interaction snap unchanged when display density changes', () => {
+    const snap = { mode: 'fixed' as const, step: 25 };
+    const sparse = resolveGridRulerMarks(viewport, 'x', {
+      kind: 'ticks',
+      specification: { mode: 'fixed', step: 50 },
+    });
+    const dense = resolveGridRulerMarks(viewport, 'x', {
+      kind: 'ticks',
+      specification: { mode: 'fixed', step: 5 },
+    });
+
+    expect(dense.length).toBeGreaterThan(sparse.length);
+    expect(snapWorldCoordinate(62, snap)).toBe(50);
+  });
+
+  test('accepts externally supplied labels without introducing domain adapters', () => {
+    expect(
+      resolveGridRulerMarks(
+        viewport,
+        'x',
+        { kind: 'ticks', specification: { mode: 'fixed', step: 20 } },
+        (tick) => `bar ${tick.position}`,
+      )[0],
+    ).toEqual({ label: 'bar 40', level: 'major', position: 0 });
+  });
+
+  test('projects horizontal marks consistently in RTL and evaluates each formatter once', () => {
+    let formatterCalls = 0;
+
+    const marks = resolveGridRulerMarks(
+      viewport,
+      'x',
+      { kind: 'ticks', specification: { mode: 'fixed', step: 20 } },
+      (tick) => {
+        formatterCalls += 1;
+        return `tick ${tick.position}`;
+      },
+      'rtl',
+    );
+
+    expect(marks.map((mark) => mark.position)).toEqual([300, 260, 220, 180, 140, 100, 60, 20]);
+    expect(formatterCalls).toBe(marks.length);
+  });
+});

package/src/features/grid-rulers/application/resolveGridRulerMarks.ts

@@ -0,0 +1,39 @@
+import {
+  getAxisCategoryTicks,
+  getAxisTicks,
+  type GridAxisName,
+  type GridAxisTick,
+  type GridViewport,
+} from '@ankhorage/grid-view';
+
+import type { GridRulerMark, GridRulerTickSource } from '../../../types/grid-rulers';
+import { projectGridRulerPosition } from './projectGridRulerPosition';
+
+/*** Resolves bounded engine ticks into viewport-pixel ruler marks without changing interaction state. */
+export function resolveGridRulerMarks(
+  viewport: GridViewport,
+  axis: GridAxisName,
+  tickSource: GridRulerTickSource,
+  formatLabel?: (tick: GridAxisTick) => string | undefined,
+  direction: 'ltr' | 'rtl' = 'ltr',
+): readonly GridRulerMark[] {
+  const ticks =
+    tickSource.kind === 'categories'
+      ? getAxisCategoryTicks(viewport, axis, tickSource.categories)
+      : getAxisTicks(viewport, axis, tickSource.specification, tickSource.provider);
+
+  return ticks.map((tick) => {
+    const formattedLabel = formatLabel?.(tick);
+
+    return {
+      position: projectGridRulerPosition(viewport, axis, tick.position, direction),
+      level: tick.level,
+      ...(tick.label !== undefined || formattedLabel !== undefined
+        ? { label: formattedLabel ?? tick.label }
+        : {}),
+      ...('categoryId' in tick && typeof tick.categoryId === 'string'
+        ? { categoryId: tick.categoryId }
+        : {}),
+    };
+  });
+}

package/src/features/grid-rulers/meta.ts

@@ -0,0 +1,26 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+const GRID_RULERS_NOTE =
+  'Requires a live viewport and optional executable tick/label providers; available through code APIs, not a serializable manifest node.';
+
+/** Passive viewport decorations intentionally remain outside direct manifest authoring. */
+export const gridLineOverlayMeta = {
+  name: 'GridLineOverlay',
+  category: 'foundation',
+  description: 'Projects bounded world-grid lines and explicit guides from a supplied viewport.',
+  directManifestNode: false,
+  note: GRID_RULERS_NOTE,
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+/** Rulers accept code-dependent tick and label providers and therefore remain code-only. */
+export const gridRulerMeta = {
+  name: 'GridRuler',
+  category: 'foundation',
+  description: 'Projects visible world-axis ticks into a passive horizontal or vertical ruler.',
+  directManifestNode: false,
+  note: GRID_RULERS_NOTE,
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/features/grid-rulers/public.ts

@@ -0,0 +1,10 @@
+export type {
+  GridGuide,
+  GridLineOverlayProps,
+  GridRulerMark,
+  GridRulerProps,
+  GridRulerTickSource,
+} from '../../types/grid-rulers';
+export { GridLineOverlay } from './adapters/inbound/GridLineOverlay';
+export { GridRuler } from './adapters/inbound/GridRuler';
+export { resolveGridRulerMarks } from './application/resolveGridRulerMarks';

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -47,6 +47,7 @@ import {
   GameOverlay,
 } from '../game/public';
 import { Gradient } from '../gradient/public';
+import { GridLineOverlay, GridRuler } from '../grid-rulers/public';
 import { GridView, TileGrid } from '../grid-view/public';
 import { Hero } from '../hero/public';
 import { Icon } from '../icon/public';
@@ -194,6 +195,8 @@ const _ZORA_COMPONENT_REGISTRY = {
   EmptyState,
   Explorer,
   FileExplorer,
+  GridLineOverlay,
+  GridRuler,
   GridView,
   TileGrid,
   MediaExplorer,

package/src/features/registry/componentMeta.ts

@@ -53,6 +53,7 @@ import { gameMeasurementProbeMeta } from '../game/meta/gameMeasurementProbeMeta'
 import { gameMeta } from '../game/meta/gameMeta';
 import { gameOverlayMeta } from '../game/meta/gameOverlayMeta';
 import { gradientMeta } from '../gradient/gradientMeta';
+import { gridLineOverlayMeta, gridRulerMeta } from '../grid-rulers/meta';
 import { gridViewMeta, tileGridMeta } from '../grid-view/meta';
 import { heroMeta } from '../hero/heroMeta';
 import { iconMeta } from '../icon/iconMeta';
@@ -198,6 +199,8 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   Explorer: explorerMeta,
   FileExplorer: fileExplorerMeta,
   MediaExplorer: mediaExplorerMeta,
+  GridLineOverlay: gridLineOverlayMeta,
+  GridRuler: gridRulerMeta,
   GridView: gridViewMeta,
   TileGrid: tileGridMeta,
   Hero: heroMeta,

package/src/index.ts

@@ -263,6 +263,14 @@ export type {
   GradientRendererProviderProps,
 } from './features/gradient/public';
 export { Gradient, GradientRendererProvider } from './features/gradient/public';
+export type {
+  GridGuide,
+  GridLineOverlayProps,
+  GridRulerMark,
+  GridRulerProps,
+  GridRulerTickSource,
+} from './features/grid-rulers/public';
+export { GridLineOverlay, GridRuler, resolveGridRulerMarks } from './features/grid-rulers/public';
 export type { GridViewProps, TileGridItem, TileGridProps } from './features/grid-view/public';
 export { GridView, layoutTileGrid, TileGrid } from './features/grid-view/public';
 export {

package/src/types/grid-rulers.ts

@@ -0,0 +1,59 @@
+import type {
+  GridAxisCategory,
+  GridAxisName,
+  GridAxisTick,
+  GridTickProvider,
+  GridTickSpecification,
+  GridViewport,
+} from '@ankhorage/grid-view';
+
+import type { ZoraBaseProps } from './base';
+
+/** A tick source is display-only; it never configures interaction snapping. */
+export type GridRulerTickSource =
+  | {
+      readonly kind: 'ticks';
+      readonly specification: GridTickSpecification;
+      readonly provider?: GridTickProvider;
+    }
+  | { readonly kind: 'categories'; readonly categories: readonly GridAxisCategory[] };
+
+/** A projected mark is measured in viewport pixels from the supplied viewport's origin. */
+export interface GridRulerMark {
+  readonly position: number;
+  readonly level: GridAxisTick['level'];
+  readonly label?: string;
+  readonly categoryId?: string;
+}
+
+/** A passive guide belongs to one world-space axis. */
+export interface GridGuide {
+  readonly id: string;
+  readonly axis: GridAxisName;
+  readonly position: number;
+  readonly label?: string;
+}
+
+/** A single horizontal or vertical passive ruler strip. */
+export interface GridRulerProps extends ZoraBaseProps {
+  readonly axis: GridAxisName;
+  readonly viewport: GridViewport;
+  readonly tickSource: GridRulerTickSource;
+  readonly thickness?: number;
+  readonly offset?: number;
+  readonly position?: 'start' | 'end';
+  readonly direction?: 'ltr' | 'rtl';
+  readonly accessibilityLabel?: string;
+  readonly formatLabel?: (tick: GridAxisTick) => string | undefined;
+}
+
+/** A passive overlay of visible major/minor grid lines and explicit guides. */
+export interface GridLineOverlayProps extends ZoraBaseProps {
+  readonly viewport: GridViewport;
+  /** Mirrors horizontal world positions using the same projection as an RTL GridRuler. */
+  readonly direction?: 'ltr' | 'rtl';
+  readonly xTickSource?: GridRulerTickSource;
+  readonly yTickSource?: GridRulerTickSource;
+  readonly guides?: readonly GridGuide[];
+  readonly accessibilityLabel?: string;
+}

package/web-dist/chunks/{Accordion-mh67wb34.js → Accordion-090y18cv.js}

@@ -20,11 +20,11 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Heading2,
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   resolveOverlayAnimation
 } from "./Accordion-n7y08rz5.js";

package/web-dist/chunks/{Accordion-7yazfxr6.js → Accordion-3d4wkzg7.js}

@@ -7,16 +7,16 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   Avatar2
-} from "./Accordion-wgejzesa.js";
+} from "./Accordion-61ntvh14.js";
 import {
   Badge2
-} from "./Accordion-qkh5yy94.js";
+} from "./Accordion-7kq500r1.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-ndf3jqhb.js → Accordion-40tenzcg.js}

@@ -1,16 +1,16 @@
 'use client';
 import {
   Button2
-} from "./Accordion-q09fjenx.js";
+} from "./Accordion-6rrqpb2h.js";
 import {
   withZoraThemeScope
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-cbfa2b8j.js → Accordion-4s68t3h7.js}

@@ -1,22 +1,22 @@
 'use client';
 import {
   Button2
-} from "./Accordion-q09fjenx.js";
+} from "./Accordion-6rrqpb2h.js";
 import {
   withZoraThemeScope
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Card2
-} from "./Accordion-xvzrx6bh.js";
+} from "./Accordion-fjxcn6g9.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   Badge2
-} from "./Accordion-qkh5yy94.js";
+} from "./Accordion-7kq500r1.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-7asr7vb0.js → Accordion-4zqd7twp.js}

@@ -4,16 +4,16 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   ButtonGroup2
-} from "./Accordion-q09fjenx.js";
+} from "./Accordion-6rrqpb2h.js";
 import {
   Card2
-} from "./Accordion-xvzrx6bh.js";
+} from "./Accordion-fjxcn6g9.js";
 import {
   List2
-} from "./Accordion-sdcfa14w.js";
+} from "./Accordion-5g05kfmx.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-sdcfa14w.js → Accordion-5g05kfmx.js}

@@ -7,14 +7,14 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   View3
 } from "./Accordion-z5a0tx18.js";
 import {
   View2,
   Divider2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Pressable
 } from "./Accordion-nnv76yff.js";
@@ -23,7 +23,7 @@ import {
 } from "./Accordion-wyxmd0n0.js";
 import {
   SectionHeader2
-} from "./Accordion-1p9r2ack.js";
+} from "./Accordion-sy1cc5my.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-wgejzesa.js → Accordion-61ntvh14.js}

@@ -4,13 +4,13 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   Icon2
-} from "./Accordion-bb8y34wh.js";
+} from "./Accordion-b96evb46.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-kkr7xfh2.js → Accordion-689w7frk.js}

@@ -1,19 +1,19 @@
 'use client';
 import {
   TileGrid2
-} from "./Accordion-54k0ncs3.js";
+} from "./Accordion-q2z00p5r.js";
 import {
   withZoraThemeScope
 } from "./Accordion-42jfy1a1.js";
 import {
   Icon2
-} from "./Accordion-bb8y34wh.js";
+} from "./Accordion-b96evb46.js";
 import {
   Image2
-} from "./Accordion-mej71qnw.js";
+} from "./Accordion-a4cma5b6.js";
 import {
   Text3
-} from "./Accordion-afmybp67.js";
+} from "./Accordion-9w8wg9mf.js";
 import {
   applySelectionIntent
 } from "./Accordion-n4et7etk.js";

package/web-dist/chunks/{Accordion-q09fjenx.js → Accordion-6rrqpb2h.js}

@@ -19,7 +19,7 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   resolveControlSize,
   resolveIconSize2,

package/web-dist/chunks/{Accordion-mej71qnw.js → Accordion-a4cma5b6.js}

@@ -7,10 +7,10 @@ import {
 } from "./Accordion-42jfy1a1.js";
 import {
   Icon2
-} from "./Accordion-bb8y34wh.js";
+} from "./Accordion-b96evb46.js";
 import {
   View2
-} from "./Accordion-f0jsd9f9.js";
+} from "./Accordion-7tjz25jh.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";