@almadar/ui 5.94.1 → 5.96.0

package/dist/components/learning/molecules/AlgorithmCanvas.d.ts

@@ -0,0 +1,58 @@
+/**
+ * AlgorithmCanvas
+ *
+ * A field-scoped learning molecule for computer-science algorithm visualizations.
+ * Projects semantic `bars` (sorting/histograms), `cells` (grids/arrays/DP tables),
+ * and `pointers` (index cursors) into pixel-space shapes on the declarative
+ * `LearningCanvas` atom, so a `.lolo` behavior never computes pixel coordinates —
+ * it just sets `bars`/`cells`/`pointers` and lets this molecule lay them out.
+ * Graph/tree algorithms reuse `BiologyCanvas` (nodes + edges); this canvas owns
+ * only the bar/cell/pointer vocabulary.
+ *
+ * @packageDocumentation
+ */
+import * as React from 'react';
+import type { LearningShape } from '../atoms/LearningCanvas';
+import type { UiError } from '../../core/atoms/types';
+export interface AlgorithmBar {
+    value: number;
+    color?: string;
+    label?: string;
+}
+export interface AlgorithmCell {
+    row: number;
+    col: number;
+    value?: number;
+    color?: string;
+    label?: string;
+}
+export interface AlgorithmPointer {
+    index: number;
+    label?: string;
+    color?: string;
+}
+export interface AlgorithmCanvasProps {
+    className?: string;
+    width?: number;
+    height?: number;
+    title?: string;
+    backgroundColor?: string;
+    /** Sorting/histogram bars; laid out left-to-right, height proportional to value. */
+    bars?: AlgorithmBar[];
+    /** Grid/array/DP cells; laid out on a row/col lattice sized to the extent. */
+    cells?: AlgorithmCell[];
+    /** Index cursors (i/j/lo/hi/mid); drawn as markers beneath the referenced bar/cell column. */
+    pointers?: AlgorithmPointer[];
+    /** Extra declarative shapes in canvas pixel coordinates. */
+    shapes?: LearningShape[];
+    interactive?: boolean;
+    animate?: boolean;
+    onShapeClick?: (payload: {
+        id?: string;
+        type?: string;
+        index: number;
+    }) => void;
+    isLoading?: boolean;
+    error?: UiError | null;
+}
+export declare const AlgorithmCanvas: React.FC<AlgorithmCanvasProps>;

package/dist/lib/atlasSlice.d.ts

@@ -0,0 +1,58 @@
+/**
+ * atlasSlice — the ONLY place a packed sheet is cut at runtime.
+ *
+ * An `Asset` may carry `{ url: <sheet.png>, atlas: <atlas.json>, sprite: <name|index> }`. This
+ * module fetches + caches the atlas JSON (a `TextureAtlas` of named sub-rects or a uniform
+ * `Tilesheet`) and resolves the source rectangle for a `sprite`, so the canvas can `drawImage`
+ * exactly that sub-region of the sheet. Coexists with the whole-PNG path (an Asset with no
+ * `atlas`/`sprite` draws the whole image) and the `useUnitSpriteAtlas` animation path.
+ *
+ * See `docs/Almadar_Std_Assets.md` §2, §7.
+ *
+ * @packageDocumentation
+ */
+import type { TextureAtlas, Tilesheet } from '@almadar/core';
+/** The minimal draw-relevant projection of an `Asset` — a sheet URL plus an optional atlas
+ *  sub-texture reference. A full `@almadar/core` `Asset` is structurally assignable. */
+export interface SpriteRef {
+    url?: string;
+    atlas?: string;
+    sprite?: string;
+}
+type ParsedAtlas = TextureAtlas | Tilesheet;
+/**
+ * Get a parsed atlas by URL, fetching+caching on first request. Returns undefined until loaded;
+ * `onReady` fires once when the fetch resolves so the caller can trigger a re-render.
+ */
+export declare function getAtlas(url: string, onReady: () => void): ParsedAtlas | undefined;
+export interface SubRect {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+}
+/**
+ * Resolve the source rect for `sprite` in `atlas`.
+ * - `TextureAtlas`: `sprite` is a SubTexture name (e.g. `"blockBrown.png"`).
+ * - `Tilesheet`: `sprite` is `"col,row"` or a flat index into the row-major grid.
+ * Returns null if the name/index doesn't resolve.
+ */
+export declare function subRectFor(atlas: ParsedAtlas, sprite: string): SubRect | null;
+/** True when the asset points into a sheet (needs slicing) rather than being a whole PNG. */
+export declare function isAtlasAsset(asset: SpriteRef | undefined | null): boolean;
+export interface AssetSource {
+    img: HTMLImageElement;
+    /** Sub-rect to blit; null = draw the whole image. */
+    rect: SubRect | null;
+    /** Source aspect ratio (width/height) — sub-rect for a slice, natural otherwise. */
+    aspect: number;
+}
+/**
+ * Resolve what to draw for `asset` given its loaded sheet `img`. Returns null when the asset is
+ * an atlas ref whose JSON isn't loaded yet (or whose sprite name doesn't resolve) — `onReady`
+ * will trigger a re-render once the fetch lands. Callers use `.aspect` to size, then `blit`.
+ */
+export declare function resolveAssetSource(img: HTMLImageElement, asset: SpriteRef | undefined | null, onReady: () => void): AssetSource | null;
+/** Draw a resolved source at `(dx,dy,dw,dh)` — sliced sub-rect or whole image. */
+export declare function blit(ctx: CanvasRenderingContext2D, src: AssetSource, dx: number, dy: number, dw: number, dh: number): void;
+export {};