@ankhorage/zora 24.0.3 → 24.1.1

package/src/features/grid-view/application/layoutTileGrid.test.ts

@@ -0,0 +1,36 @@
+import { getVisibleGridItems } from '@ankhorage/grid-view';
+import { describe, expect, test } from 'bun:test';
+
+import { layoutTileGrid } from './layoutTileGrid';
+
+describe('TileGrid presentation', () => {
+  test('uses a responsive count of columns and stable item IDs', () => {
+    const items = Array.from({ length: 10000 }, (_, index) => ({ id: String(index) }));
+    const small = layoutTileGrid(items, 270, 120, 10);
+    const large = layoutTileGrid(items, 530, 120, 10);
+    expect(small.columns).toBe(2);
+    expect(large.columns).toBe(4);
+    expect(small.items[2]).toEqual({ id: '2', x: 0, y: 130, width: 120, height: 120 });
+    expect(small.items[9999]?.id).toBe('9999');
+  });
+
+  test('mounts only the viewport subset from a large catalogue', () => {
+    const items = Array.from({ length: 10000 }, (_, index) => ({ id: String(index) }));
+    const layout = layoutTileGrid(items, 270, 120, 10);
+    const visible = getVisibleGridItems(layout.items, {
+      width: 270,
+      height: 250,
+      offsetX: 0,
+      offsetY: 0,
+      pixelsPerUnitX: 1,
+      pixelsPerUnitY: 1,
+    });
+    expect(visible.map((item) => item.id)).toEqual(['0', '1', '2', '3']);
+  });
+
+  test('zoom affects column count without changing stable item identity', () => {
+    const items = [{ id: 'a' }, { id: 'b' }];
+    expect(layoutTileGrid(items, 500, 100, 10, 2).columns).toBe(2);
+    expect(layoutTileGrid(items, 500, 100, 10, 1).columns).toBe(4);
+  });
+});

package/src/features/grid-view/application/layoutTileGrid.ts

@@ -0,0 +1,46 @@
+import type { GridRectItem } from '@ankhorage/grid-view';
+
+import type { TileGridItem } from '../../../types/grid-view';
+
+/** A presentation-level spatial layout, expressed in engine-owned world rectangles. */
+export interface TileGridLayout {
+  readonly items: readonly GridRectItem[];
+  readonly width: number;
+  readonly height: number;
+  readonly columns: number;
+}
+
+/*** Arrange keyed tiles into responsive rows without constructing placeholder grid cells. */
+export function layoutTileGrid(
+  items: readonly TileGridItem[],
+  viewportWidth: number,
+  tileSize: number,
+  gap: number,
+  zoom = 1,
+): TileGridLayout {
+  if (
+    ![viewportWidth, tileSize, gap, zoom].every(Number.isFinite) ||
+    viewportWidth < 0 ||
+    tileSize <= 0 ||
+    gap < 0 ||
+    zoom <= 0
+  ) {
+    throw new RangeError(
+      'Tile layout requires finite, nonnegative dimensions and positive scales.',
+    );
+  }
+  const columns = Math.max(1, Math.floor((viewportWidth / zoom + gap) / (tileSize + gap)));
+  const rows = Math.ceil(items.length / columns);
+  return {
+    columns,
+    width: columns * (tileSize + gap) - gap,
+    height: Math.max(0, rows * (tileSize + gap) - gap),
+    items: items.map((item, index) => ({
+      id: item.id,
+      x: (index % columns) * (tileSize + gap),
+      y: Math.floor(index / columns) * (tileSize + gap),
+      width: tileSize,
+      height: tileSize,
+    })),
+  };
+}

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

@@ -0,0 +1,22 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+/** Code-only render callbacks are deliberately excluded from the serializable manifest boundary. */
+export const gridViewMeta = {
+  name: 'GridView',
+  category: 'foundation',
+  description: 'Viewport renderer for world-placed items. Render callbacks belong to code APIs.',
+  directManifestNode: false,
+  note: 'Requires executable renderItem callbacks; available through code APIs, not a serializable manifest node.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const tileGridMeta = {
+  name: 'TileGrid',
+  category: 'foundation',
+  description: 'Virtualized tile composition. Item rendering is a code API.',
+  directManifestNode: false,
+  note: 'Requires a renderItem callback; use MediaExplorer or FileExplorer for manifest-authored tiles.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

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

@@ -0,0 +1,4 @@
+export type { GridViewProps, TileGridItem, TileGridProps } from '../../types/grid-view';
+export { GridView } from './adapters/inbound/GridView';
+export { TileGrid } from './adapters/inbound/TileGrid';
+export { layoutTileGrid } from './application/layoutTileGrid';

package/src/features/layout/public.test.ts

@@ -17,7 +17,6 @@ const removedPublicNames = [
   'SidebarLayout',
   'Spacer',
   'Stack',
-  'TileGrid',
   'TopbarLayout',
 ] as const;
 
@@ -27,6 +26,11 @@ describe('canonical layout boundary', () => {
       expect(publicSource).toMatch(new RegExp(`\\b${name}\\b`, 'u'));
     }
 
+    expect(publicSource).not.toContain('TileGrid');
+    expect(rootSource).toContain(
+      "export { GridView, layoutTileGrid, TileGrid } from './features/grid-view/public';",
+    );
+
     for (const name of removedPublicNames) {
       expect(publicSource).not.toMatch(new RegExp(`\\b${name}\\b`, 'u'));
       expect(rootSource).not.toMatch(new RegExp(`export[^\\n]*\\b${name}\\b`, 'u'));

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -30,6 +30,7 @@ import { DataTable } from '../data-table/public';
 import { DatePicker } from '../date-picker/public';
 import { Dialog } from '../dialog/public';
 import { EmptyState } from '../empty-state/public';
+import { Explorer, FileExplorer, MediaExplorer } from '../explorer/public';
 import { Checkbox, CheckboxGroup } from '../form/checkbox/public';
 import { Field, Form, FormActions, FormError } from '../form/public';
 import { Radio, RadioGroup } from '../form/radio/public';
@@ -46,6 +47,7 @@ import {
   GameOverlay,
 } from '../game/public';
 import { Gradient } from '../gradient/public';
+import { GridView, TileGrid } from '../grid-view/public';
 import { Hero } from '../hero/public';
 import { Icon } from '../icon/public';
 import { Image } from '../image/public';
@@ -190,6 +192,11 @@ const _ZORA_COMPONENT_REGISTRY = {
   CollectionEditor,
   ContentRail,
   EmptyState,
+  Explorer,
+  FileExplorer,
+  GridView,
+  TileGrid,
+  MediaExplorer,
   Hero,
   List,
   ListItem,

package/src/features/registry/componentMeta.test.ts

@@ -192,6 +192,8 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'IconButton',
       'MetricCard',
       'Uploader',
+      'MediaExplorer',
+      'FileExplorer',
       'SectionHeader',
       'EmptyState',
       'Hero',

package/src/features/registry/componentMeta.ts

@@ -35,6 +35,7 @@ import { dataTableMeta } from '../data-table/dataTableMeta';
 import { datePickerMeta } from '../date-picker/datePickerMeta';
 import { dialogMeta } from '../dialog/dialogMeta';
 import { emptyStateMeta } from '../empty-state/emptyStateMeta';
+import { explorerMeta, fileExplorerMeta, mediaExplorerMeta } from '../explorer/meta';
 import { checkboxGroupMeta, checkboxMeta } from '../form/checkbox/checkboxMeta';
 import { fieldMeta } from '../form/field/meta';
 import { formActionsMeta } from '../form/formActionsMeta';
@@ -52,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 { gridViewMeta, tileGridMeta } from '../grid-view/meta';
 import { heroMeta } from '../hero/heroMeta';
 import { iconMeta } from '../icon/iconMeta';
 import { imageMeta } from '../image/imageMeta';
@@ -193,6 +195,11 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   CollectionEditor: collectionEditorMeta,
   ContentRail: contentRailMeta,
   EmptyState: emptyStateMeta,
+  Explorer: explorerMeta,
+  FileExplorer: fileExplorerMeta,
+  MediaExplorer: mediaExplorerMeta,
+  GridView: gridViewMeta,
+  TileGrid: tileGridMeta,
   Hero: heroMeta,
   List: listMeta,
   ListItem: listItemMeta,

package/src/features/uploader/adapters/inbound/Uploader.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import type { UploadAsset, UploaderProps, UploadType } from '../../../../types/upload';
 import { Button } from '../../../button/public';
 import { Dialog } from '../../../dialog/public';
+import { Explorer } from '../../../explorer/public';
 import { Field } from '../../../form/public';
 import { Icon } from '../../../icon/public';
 import { Image } from '../../../image/public';
@@ -40,6 +41,7 @@ function UploaderInner({
   disabled = false,
   readOnly = false,
   validatePicked,
+  explorerItems,
   onUpload,
   onRemove,
   aspectRatio = 1,
@@ -54,6 +56,7 @@ function UploaderInner({
   const removing = internalRemoving || uploadState === 'removing';
   const [progress, setProgress] = React.useState<number | null>(null);
   const [previewOpen, setPreviewOpen] = React.useState(false);
+  const [explorerOpen, setExplorerOpen] = React.useState(false);
   const mountedRef = React.useRef<boolean | null>(null);
   const resolvedAccept = resolveUploadAccept(type, accept);
   const actionsDisabled = disabled || readOnly;
@@ -87,19 +90,10 @@ function UploaderInner({
     [isMounted],
   );
 
-  const handlePick = React.useCallback(async () => {
-    if (passive || actionsDisabled || uploading || removing) {
-      return;
-    }
-
-    setInternalError(undefined);
-
-    try {
-      const picked = await picker.pickAsync({ accept: resolvedAccept, type });
-      if (!picked || !isMounted()) {
-        return;
-      }
-
+  const acceptPicked = React.useCallback(
+    async (picked: UploadAsset | null) => {
+      if (!picked || !isMounted() || passive || actionsDisabled || uploading || removing) return;
+      setInternalError(undefined);
       const validationError = validateUploadAsset({
         accept: resolvedAccept,
         asset: picked,
@@ -111,55 +105,65 @@ function UploaderInner({
         onValidationError?.({ message: validationError });
         return;
       }
-
       notifyValue(picked);
       onUploadRequest?.({ asset: picked });
-      if (!onUpload) {
-        return;
-      }
+      if (!onUpload) return;
 
       setUploading(true);
       setProgressSafe(0);
-
       try {
         const uploaded = await onUpload(picked, { setProgress: setProgressSafe });
-        if (!isMounted()) {
-          return;
-        }
-
+        if (!isMounted()) return;
         notifyValue(uploaded);
         setUploading(false);
         setProgress(null);
       } catch (error) {
-        if (!isMounted()) {
-          return;
-        }
-
+        if (!isMounted()) return;
         setInternalError(formatUnknownError(error));
         setUploading(false);
         setProgress(null);
       }
+    },
+    [
+      actionsDisabled,
+      isMounted,
+      maxSizeBytes,
+      notifyValue,
+      onUpload,
+      onUploadRequest,
+      onValidationError,
+      passive,
+      removing,
+      resolvedAccept,
+      setProgressSafe,
+      uploading,
+      validatePicked,
+    ],
+  );
+
+  const handlePick = React.useCallback(async () => {
+    if (passive || actionsDisabled || uploading || removing) return;
+    if (explorerItems !== undefined) {
+      setExplorerOpen(true);
+      return;
+    }
+    setInternalError(undefined);
+    try {
+      await acceptPicked(await picker.pickAsync({ accept: resolvedAccept, type }));
     } catch (error) {
-      if (isMounted()) {
-        setInternalError(formatUnknownError(error));
-      }
+      if (isMounted()) setInternalError(formatUnknownError(error));
     }
   }, [
+    acceptPicked,
     actionsDisabled,
+    explorerItems,
     isMounted,
-    maxSizeBytes,
-    notifyValue,
-    onUploadRequest,
-    onValidationError,
-    onUpload,
     passive,
     picker,
     removing,
     resolvedAccept,
-    setProgressSafe,
     type,
     uploading,
-    validatePicked,
   ]);
 
   const handleRemove = React.useCallback(async () => {
@@ -287,6 +291,31 @@ function UploaderInner({
         </View>
       </Field>
 
+      {explorerItems !== undefined ? (
+        <Dialog
+          closeOnBackdrop
+          interactionPolicy={interactionPolicy}
+          onDismiss={() => setExplorerOpen(false)}
+          title="Select from collection"
+          visible={explorerOpen}
+        >
+          <Explorer
+            items={explorerItems}
+            height={360}
+            interactionPolicy={interactionPolicy}
+            onActivate={({ id }) => {
+              const chosen = explorerItems.find((item) => item.id === id)?.uploadAsset;
+              setExplorerOpen(false);
+              if (chosen) {
+                void acceptPicked(chosen).catch((error: unknown) => {
+                  if (isMounted()) setInternalError(formatUnknownError(error));
+                });
+              }
+            }}
+          />
+        </Dialog>
+      ) : null}
+
       {canPreviewImage ? (
         <Dialog
           closeOnBackdrop

package/src/features/uploader/public.ts

@@ -1,6 +1,7 @@
 export type {
   UploadAsset,
   UploadAssetBase,
+  UploaderExplorerItem,
   UploaderProps,
   UploadProgressContext,
   UploadType,

package/src/features/uploader/uploaderMeta.ts

@@ -54,6 +54,7 @@ export const uploaderMeta = {
     type: { type: 'enum', category: 'Selection', enum: ['image', 'video', 'document', 'file'] },
     accept: { type: 'string', category: 'Validation' },
     maxSizeBytes: { type: 'number', category: 'Validation' },
+    explorerItems: { type: 'array', category: 'Selection', label: 'App-owned collection' },
     required: { type: 'boolean', category: 'Validation' },
     disabled: { type: 'boolean', category: 'State' },
     readOnly: { type: 'boolean', category: 'State' },

package/src/index.ts

@@ -169,6 +169,20 @@ export {
   type EmptyStateAction,
   type EmptyStateProps,
 } from './features/empty-state/public';
+export type {
+  ExplorerActivateEvent,
+  ExplorerItem,
+  ExplorerItemKind,
+  ExplorerProps,
+  ExplorerSelectionChangeEvent,
+  ExplorerSelectionMode,
+} from './features/explorer/public';
+export {
+  Explorer,
+  FileExplorer,
+  MediaExplorer,
+  resolveExplorerSelection,
+} from './features/explorer/public';
 export {
   Checkbox,
   CheckboxGroup,
@@ -249,6 +263,8 @@ export type {
   GradientRendererProviderProps,
 } from './features/gradient/public';
 export { Gradient, GradientRendererProvider } from './features/gradient/public';
+export type { GridViewProps, TileGridItem, TileGridProps } from './features/grid-view/public';
+export { GridView, layoutTileGrid, TileGrid } from './features/grid-view/public';
 export {
   Hero,
   type HeroAction,
@@ -494,6 +510,7 @@ export { Text } from './features/typography/public';
 export type {
   UploadAsset,
   UploadAssetBase,
+  UploaderExplorerItem,
   UploaderProps,
   UploadProgressContext,
   UploadType,

package/src/types/explorer.ts

@@ -0,0 +1,45 @@
+import type { ZoraBaseProps } from './base';
+
+/** Portable catalogue row. Providers retain permissions, pagination and storage objects. */
+export type ExplorerItemKind = 'image' | 'video' | 'audio' | 'document' | 'file' | 'folder';
+
+export interface ExplorerItem {
+  readonly id: string;
+  readonly kind: ExplorerItemKind;
+  readonly name: string;
+  readonly thumbnailUri?: string;
+  readonly uri?: string;
+  readonly contentType?: string;
+  readonly sizeBytes?: number;
+  readonly durationSeconds?: number;
+  readonly providerId?: string;
+  readonly disabled?: boolean;
+}
+
+export type ExplorerSelectionMode = 'single' | 'multi';
+
+export interface ExplorerActivateEvent {
+  readonly id: string;
+}
+
+export interface ExplorerSelectionChangeEvent {
+  readonly selectedIds: readonly string[];
+}
+
+export interface ExplorerProps extends ZoraBaseProps {
+  items: readonly ExplorerItem[];
+  selectionMode?: ExplorerSelectionMode;
+  selectedIds?: readonly string[];
+  defaultSelectedIds?: readonly string[];
+  onSelectionChange?: (event: ExplorerSelectionChangeEvent) => void;
+  onActivate?: (event: ExplorerActivateEvent) => void;
+  width?: number;
+  height?: number;
+  tileSize?: number;
+  zoom?: number;
+  loading?: boolean;
+  errorText?: string;
+  emptyText?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+}

package/src/types/grid-view.ts

@@ -0,0 +1,34 @@
+import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import type React from 'react';
+
+import type { ZoraBaseProps } from './base';
+
+/** The renderer owns presentation only; world geometry comes from grid-view. */
+export interface GridViewProps extends ZoraBaseProps {
+  items: readonly GridRectItem[];
+  contentWidth: number;
+  contentHeight: number;
+  width: number;
+  height: number;
+  zoom?: number;
+  overscanPixels?: number;
+  onViewportChange?: (viewport: GridViewport) => void;
+  renderItem: (item: GridRectItem) => React.ReactNode;
+}
+
+/** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */
+export interface TileGridItem {
+  readonly id: string;
+}
+
+/** Reusable tile presentation based on the generic world/viewport engine. */
+export interface TileGridProps extends ZoraBaseProps {
+  items: readonly TileGridItem[];
+  width?: number;
+  height?: number;
+  tileSize?: number;
+  gap?: number;
+  zoom?: number;
+  overscanPixels?: number;
+  renderItem: (item: TileGridItem) => React.ReactNode;
+}

package/src/types/upload.ts

@@ -1,6 +1,7 @@
 import type React from 'react';
 
 import type { ZoraBaseProps } from './base';
+import type { ExplorerItem } from './explorer';
 
 export type UploadType = 'image' | 'video' | 'document' | 'file';
 
@@ -42,6 +43,8 @@ export interface ValidateUploadAssetInput {
   validate?: (asset: UploadAsset) => string | undefined;
 }
 
+export type UploaderExplorerItem = ExplorerItem & { readonly uploadAsset: UploadAsset };
+
 export interface UploaderProps extends ZoraBaseProps {
   value?: UploadAsset | null;
   onChange?: (next: UploadAsset | null) => void;
@@ -62,6 +65,8 @@ export interface UploaderProps extends ZoraBaseProps {
   disabled?: boolean;
   readOnly?: boolean;
   validatePicked?: (asset: UploadAsset) => string | undefined;
+  /** If supplied, Uploader opens the canonical app-owned Explorer instead of an OS picker. */
+  explorerItems?: readonly UploaderExplorerItem[];
   onUpload?: (asset: UploadAsset, context: UploadProgressContext) => Promise<UploadAsset>;
   onRemove?: (current: UploadAsset) => void | Promise<void>;
   aspectRatio?: number;

package/web-dist/chunks/{Accordion-ansfkmye.js → Accordion-016wvwpg.js}

@@ -1,13 +1,13 @@
 'use client';
-import {
-  require_cjs
-} from "./Accordion-sek2q4r1.js";
 import {
   withZoraThemeScope
-} from "./Accordion-74rt38d4.js";
+} from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-vewrj1kr.js";
+} from "./Accordion-f0jsd9f9.js";
+import {
+  require_cjs
+} from "./Accordion-xgpzh4wq.js";
 import {
   __toESM
 } from "./Accordion-nh0cs9hq.js";

package/web-dist/chunks/{Accordion-3hg1wprb.js → Accordion-09qs8gt1.js}

@@ -1,7 +1,7 @@
 'use client';
 import {
   require_cjs
-} from "./Accordion-sek2q4r1.js";
+} from "./Accordion-xgpzh4wq.js";
 import {
   __toESM
 } from "./Accordion-nh0cs9hq.js";

package/web-dist/chunks/{Accordion-kpap0trj.js → Accordion-184r2r82.js}

@@ -1,7 +1,7 @@
 'use client';
 import {
   resolveResponsive
-} from "./Accordion-3hg1wprb.js";
+} from "./Accordion-09qs8gt1.js";
 import {
   resolveToken
 } from "./Accordion-fre84yaq.js";

package/web-dist/chunks/{Accordion-jdwwf626.js → Accordion-1p9r2ack.js}

@@ -1,14 +1,14 @@
 'use client';
 import {
   withZoraThemeScope
-} from "./Accordion-74rt38d4.js";
+} from "./Accordion-42jfy1a1.js";
 import {
   View2
-} from "./Accordion-vewrj1kr.js";
+} from "./Accordion-f0jsd9f9.js";
 import {
   Heading2,
   Text3
-} from "./Accordion-t3hm5tcv.js";
+} from "./Accordion-afmybp67.js";
 
 // src/features/section/adapters/inbound/SectionHeader.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/web-dist/chunks/{Accordion-2q6p67xe.js → Accordion-2c759z0y.js}

@@ -1,23 +1,25 @@
 'use client';
 import {
   View3
-} from "./Accordion-sxzax4x4.js";
+} from "./Accordion-z5a0tx18.js";
 import {
-  require_cjs,
   useTheme
-} from "./Accordion-sek2q4r1.js";
+} from "./Accordion-6wrr910w.js";
 import {
   Surface3
-} from "./Accordion-rkt7qdmj.js";
+} from "./Accordion-2nesr9cv.js";
 import {
   Text2
-} from "./Accordion-kpxyryke.js";
+} from "./Accordion-wyxmd0n0.js";
 import {
   Portal
 } from "./Accordion-0gfsj9qh.js";
 import {
   resolveOverlayAnimation
 } from "./Accordion-n7y08rz5.js";
+import {
+  require_cjs
+} from "./Accordion-xgpzh4wq.js";
 import {
   __toESM
 } from "./Accordion-nh0cs9hq.js";