@snap-rail/framework-shadcn 0.0.0-stage → 0.2.0

package/lib/types/variables.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The variable seam: demand plugins declare the process variables they
+ * listen to — a device, a group, a name, and a semantic type, nothing
+ * protocol-specific — and mapping surfaces (a driver's settings page) list
+ * the registry to wire those declarations onto real register addresses.
+ * Point names are unique only within their group, so a declaration is
+ * itself the full address — the same (device, group, name) triple the field
+ * seam speaks natively; consumers ride `field.points.subscribe` /
+ * `field/point-updated` with no id munging.
+ *
+ * Bindings (below the registry) generalize consumption: a page addresses
+ * field data as a device-qualified point (`{device, group, name}`) or a
+ * device's whole business group (`{device, group}`) and gets a live
+ * aggregated view (any member active ⇒ the group is active with the member
+ * names). Group membership is mapping configuration served by the field
+ * seam's generic mapping document (`field.mappings.list`, dialect-free), so
+ * a `field/mappings-changed` frame re-resolves the binding in place.
+ *
+ * @module @snap-rail/framework-shadcn/variables
+ */
+import { Context, type Plugin } from '@snap-rail/cordis';
+import { type MappingDocument, type PointRef, type PointType, type PointValue } from '@snap-rail/equipment/contract';
+/** What one demand plugin contributes: the variable it wants to hear about,
+ * addressed by its full triple. */
+export interface VariableDef {
+    /** The device the variable lives on. */
+    device: string;
+    /** The business group the variable lives in. */
+    group: string;
+    /** Point name within the group (unique there, not globally). */
+    name: string;
+    /** Semantic value type (the field seam's type vocabulary). */
+    type: PointType;
+    /** Human-facing label for mapping surfaces. */
+    title?: string;
+}
+/** A registered variable as mapping surfaces see it. */
+export interface VariableEntry extends VariableDef {
+    /** Where the declaration came from (phase 1: plugin code only). */
+    source: 'plugin';
+}
+/** Variable registry exposed as `ctx.variables`. */
+export interface VariablesService {
+    /** Registered variables in registration order. */
+    list(): readonly VariableEntry[];
+    /** Register variables; disposal (caller unload) removes them all.
+     * The (device, group, name) triple is the uniqueness contract: a
+     * same-address re-registration replaces the earlier one.
+     * @param caller - owning context; unload drops every def in the call.
+     * @param defs - the declarations; duplicate addresses inside one call throw.
+     */
+    register(caller: Context, defs: readonly VariableDef[]): () => void;
+}
+declare module '@snap-rail/cordis' {
+    interface Context {
+        variables: VariablesService;
+    }
+    interface Events {
+        /** The variable registry changed (add, replace, or removal). */
+        'variables/changed'(): void;
+    }
+}
+/**
+ * Mounts the `ctx.variables` registry. All state lives in construction-time
+ * closures: traceable context proxies rebind `this` on every method access,
+ * so `this`-reached state cannot back a service here (the uiSlots lesson).
+ */
+declare const variablesPlugin: Plugin.Object<void>;
+export default variablesPlugin;
+/** How a demand page addresses field data: one device-qualified point or a
+ * device's whole business group. The triple is mandatory — point names are
+ * group-scoped, so a bare name cannot address anything. */
+export type FieldBinding = {
+    device: string;
+    group: string;
+    name: string;
+} | {
+    device: string;
+    group: string;
+};
+/** One resolved group member: its field address plus display name. */
+export interface ResolvedMember {
+    ref: PointRef;
+    name: string;
+}
+/** A binding after resolution against the mapping document. */
+export type ResolvedBinding = {
+    kind: 'point';
+    ref: PointRef;
+    name: string;
+} | {
+    kind: 'group';
+    device: string;
+    group: string;
+    members: readonly ResolvedMember[];
+};
+/**
+ * Resolve a binding against the generic mapping document. The device must
+ * exist, the group entity must exist on it, and the point form must find
+ * the point in exactly that group — an unknown group name must read as
+ * unresolved, never as "all normal". A group resolves with at least one
+ * member, in the document's order (the driver's projection defines it; the
+ * first active member is a stable "primary").
+ */
+export declare function resolveBinding(doc: MappingDocument, binding: FieldBinding): ResolvedBinding | undefined;
+/** One active group member with the sample that activated it. */
+export interface BoundMember {
+    /** The point name — the business name a group view surfaces. */
+    name: string;
+    value: PointValue;
+    time: number;
+}
+/** The live view of a binding a listener receives. */
+export type BindingView = {
+    kind: 'unresolved';
+} | {
+    kind: 'point';
+    ref: PointRef;
+    name: string;
+    sample: {
+        value: PointValue;
+        time: number;
+    } | undefined;
+} | {
+    kind: 'group';
+    device: string;
+    group: string;
+    /** `active` when any member is truthy; `normal` otherwise. */
+    status: 'normal' | 'active';
+    /** Active members in group display order (see `resolveBinding`). */
+    active: readonly BoundMember[];
+    /** Members whose latest sample is `null` (link abnormal after observing). */
+    abnormal: readonly string[];
+    /** Mapped members with no observation yet. */
+    pending: readonly string[];
+};
+/**
+ * Watch one binding and emit a `BindingView` on every change. The watcher
+ * resolves the generic mapping document itself, seeds current values with
+ * one `field.points.read`, follows `field/point-updated` frames, and
+ * re-resolves on a `field/mappings-changed` frame — re-mapping takes effect
+ * without remounting the consumer.
+ *
+ * The returned stop function drops this watcher's subscription references;
+ * the host counts references per address, so overlapping watchers of one
+ * address never starve each other.
+ */
+export declare function watchBinding(ctx: Context, binding: FieldBinding, listener: (view: BindingView) => void): () => void;
+/** The React recipe over `watchBinding`; `unresolved` until first observation. */
+export declare function useBinding(ctx: Context, binding: FieldBinding): BindingView;
+/**
+ * The consume recipe for demand plugins: seed the current value with a
+ * `field.points.read`, then follow `field/point-updated` increments. Returns
+ * `undefined` until the first observation — an unmapped declaration stays
+ * undefined.
+ *
+ * The hook holds one subscription reference for its lifetime; the matching
+ * `field.points.unsubscribe` fires on unmount, and the host's reference
+ * counting keeps other watchers of the same address live.
+ */
+export declare function usePoint(ctx: Context, binding: {
+    device: string;
+    group: string;
+    name: string;
+}): {
+    value: PointValue;
+    time: number;
+} | undefined;

package/lib/types/variables.js

@@ -0,0 +1,282 @@
+/**
+ * The variable seam: demand plugins declare the process variables they
+ * listen to — a device, a group, a name, and a semantic type, nothing
+ * protocol-specific — and mapping surfaces (a driver's settings page) list
+ * the registry to wire those declarations onto real register addresses.
+ * Point names are unique only within their group, so a declaration is
+ * itself the full address — the same (device, group, name) triple the field
+ * seam speaks natively; consumers ride `field.points.subscribe` /
+ * `field/point-updated` with no id munging.
+ *
+ * Bindings (below the registry) generalize consumption: a page addresses
+ * field data as a device-qualified point (`{device, group, name}`) or a
+ * device's whole business group (`{device, group}`) and gets a live
+ * aggregated view (any member active ⇒ the group is active with the member
+ * names). Group membership is mapping configuration served by the field
+ * seam's generic mapping document (`field.mappings.list`, dialect-free), so
+ * a `field/mappings-changed` frame re-resolves the binding in place.
+ *
+ * @module @snap-rail/framework-shadcn/variables
+ */
+import { Context } from '@snap-rail/cordis';
+import { subscribeFrame } from '@snap-rail/connection';
+import { equipmentFrameSchemas, pointKey, } from '@snap-rail/equipment/contract';
+import { useEffect, useState } from 'react';
+/**
+ * Mounts the `ctx.variables` registry. All state lives in construction-time
+ * closures: traceable context proxies rebind `this` on every method access,
+ * so `this`-reached state cannot back a service here (the uiSlots lesson).
+ */
+const variablesPlugin = {
+    name: 'client-variables',
+    apply(ctx) {
+        const variables = new Map();
+        ctx.provide('variables', {
+            list() {
+                return [...variables.values()];
+            },
+            register(caller, defs) {
+                const keys = defs.map(def => pointKey(def));
+                if (new Set(keys).size !== keys.length) {
+                    throw new Error(`variables: duplicate addresses in one registration: ${keys.join(', ')}`);
+                }
+                const installed = [];
+                for (const def of defs) {
+                    const entry = { ...def, source: 'plugin' };
+                    const key = pointKey(def);
+                    installed.push({ key, entry });
+                    variables.set(key, entry);
+                }
+                ctx.emit('variables/changed');
+                const remove = () => {
+                    let changed = false;
+                    for (const { key, entry } of installed) {
+                        // Identity check: only drop addresses this call still owns (a
+                        // later re-registration by someone else stays).
+                        if (variables.get(key) === entry) {
+                            variables.delete(key);
+                            changed = true;
+                        }
+                    }
+                    if (changed)
+                        ctx.emit('variables/changed');
+                };
+                // Effects take a body producing the disposer; passing `remove`
+                // itself would run it as setup.
+                caller.effect(() => remove);
+                return remove;
+            },
+        });
+    },
+};
+export default variablesPlugin;
+/**
+ * Resolve a binding against the generic mapping document. The device must
+ * exist, the group entity must exist on it, and the point form must find
+ * the point in exactly that group — an unknown group name must read as
+ * unresolved, never as "all normal". A group resolves with at least one
+ * member, in the document's order (the driver's projection defines it; the
+ * first active member is a stable "primary").
+ */
+export function resolveBinding(doc, binding) {
+    if (!doc.devices.some(device => device.id === binding.device))
+        return undefined;
+    if (!doc.groups.some(group => group.deviceId === binding.device && group.name === binding.group))
+        return undefined;
+    if ('name' in binding) {
+        const mapped = doc.points.some(point => point.deviceId === binding.device && point.group === binding.group && point.name === binding.name);
+        if (!mapped)
+            return undefined;
+        return {
+            kind: 'point',
+            ref: { device: binding.device, group: binding.group, name: binding.name },
+            name: binding.name,
+        };
+    }
+    const members = doc.points
+        .filter(point => point.deviceId === binding.device && point.group === binding.group)
+        .map(point => ({ ref: { device: point.deviceId, group: point.group, name: point.name }, name: point.name }));
+    if (members.length === 0)
+        return undefined;
+    return { kind: 'group', device: binding.device, group: binding.group, members };
+}
+/** Any-active truthiness: `true`, a nonzero number/bigint, a non-empty string. */
+function isActiveValue(value) {
+    if (value === null)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'bigint')
+        return value !== 0n;
+    if (typeof value === 'number')
+        return value !== 0;
+    return value.length > 0;
+}
+/**
+ * Watch one binding and emit a `BindingView` on every change. The watcher
+ * resolves the generic mapping document itself, seeds current values with
+ * one `field.points.read`, follows `field/point-updated` frames, and
+ * re-resolves on a `field/mappings-changed` frame — re-mapping takes effect
+ * without remounting the consumer.
+ *
+ * The returned stop function drops this watcher's subscription references;
+ * the host counts references per address, so overlapping watchers of one
+ * address never starve each other.
+ */
+export function watchBinding(ctx, binding, listener) {
+    const { link } = ctx.client;
+    let live = true;
+    let resolved;
+    let refs = [];
+    const samples = new Map();
+    const compute = () => {
+        if (resolved === undefined) {
+            listener({ kind: 'unresolved' });
+            return;
+        }
+        if (resolved.kind === 'point') {
+            listener({ kind: 'point', ref: resolved.ref, name: resolved.name, sample: samples.get(pointKey(resolved.ref)) });
+            return;
+        }
+        const active = [];
+        const abnormal = [];
+        const pending = [];
+        for (const member of resolved.members) {
+            const sample = samples.get(pointKey(member.ref));
+            // `null` with `time` 0 is the field seam's "registered but never
+            // observed" read; a `null` with a real timestamp is link abnormal.
+            if (sample === undefined || (sample.value === null && sample.time === 0))
+                pending.push(member.name);
+            else if (sample.value === null)
+                abnormal.push(member.name);
+            else if (isActiveValue(sample.value))
+                active.push({ name: member.name, value: sample.value, time: sample.time });
+        }
+        listener({
+            kind: 'group',
+            device: resolved.device,
+            group: resolved.group,
+            status: active.length > 0 ? 'active' : 'normal',
+            active,
+            abnormal,
+            pending,
+        });
+    };
+    const resubscribe = () => {
+        void link.call('equipment.mappings.list', {})
+            .then(result => {
+            if (!live || !result.ok)
+                return;
+            const next = resolveBinding(result.value.mappings, binding);
+            const nextRefs = next === undefined ? [] : next.kind === 'point' ? [next.ref] : next.members.map(member => member.ref);
+            const wanted = new Set(nextRefs.map(pointKey));
+            for (const ref of refs) {
+                if (!wanted.has(pointKey(ref)))
+                    void link.call('equipment.points.unsubscribe', { points: [ref] }).catch(() => { });
+            }
+            for (const ref of nextRefs) {
+                if (!refs.some(current => pointKey(current) === pointKey(ref))) {
+                    void link.call('equipment.points.subscribe', { points: [ref] }).catch(() => { });
+                }
+            }
+            refs = nextRefs;
+            resolved = next;
+            samples.clear();
+            if (nextRefs.length === 0) {
+                compute();
+                return;
+            }
+            void link.call('equipment.points.read', { points: [...nextRefs] })
+                .then(read => {
+                if (!live)
+                    return;
+                if (read.ok) {
+                    for (const sample of read.value.samples) {
+                        samples.set(pointKey(sample), { value: sample.value, time: sample.time });
+                    }
+                }
+                // A read mixing registered and unregistered addresses fails
+                // wholesale (not-found); compute anyway — the missing members
+                // simply read as pending until the rig catches up.
+                compute();
+            })
+                .catch(() => {
+                // The call itself failed (carrier); the view observes nothing yet.
+                if (live)
+                    compute();
+            });
+        })
+            .catch(() => { });
+    };
+    const detachUpdates = subscribeFrame(link, 'equipment/point-updated', equipmentFrameSchemas['equipment/point-updated'], frame => {
+        const ref = { device: frame.device, group: frame.group, name: frame.name };
+        if (!refs.some(current => pointKey(current) === pointKey(ref)))
+            return;
+        samples.set(pointKey(ref), { value: frame.value, time: frame.time });
+        compute();
+    });
+    const detachConfig = link.subscribe('equipment/mappings-changed', () => { resubscribe(); });
+    resubscribe();
+    return () => {
+        live = false;
+        detachUpdates();
+        detachConfig();
+        if (refs.length > 0)
+            void link.call('equipment.points.unsubscribe', { points: [...refs] }).catch(() => { });
+    };
+}
+/** Stable identity of a binding for hook dependency lists. */
+function bindingKey(binding) {
+    return 'name' in binding
+        ? `${binding.device}/${binding.group}/${binding.name}`
+        : `${binding.device}/${binding.group}`;
+}
+/** The React recipe over `watchBinding`; `unresolved` until first observation. */
+export function useBinding(ctx, binding) {
+    const [view, setView] = useState({ kind: 'unresolved' });
+    const { link } = ctx.client;
+    const key = bindingKey(binding);
+    useEffect(() => watchBinding(ctx, binding, setView), [link, key]);
+    return view;
+}
+/**
+ * The consume recipe for demand plugins: seed the current value with a
+ * `field.points.read`, then follow `field/point-updated` increments. Returns
+ * `undefined` until the first observation — an unmapped declaration stays
+ * undefined.
+ *
+ * The hook holds one subscription reference for its lifetime; the matching
+ * `field.points.unsubscribe` fires on unmount, and the host's reference
+ * counting keeps other watchers of the same address live.
+ */
+export function usePoint(ctx, binding) {
+    const [sample, setSample] = useState(undefined);
+    const { link } = ctx.client;
+    const key = pointKey(binding);
+    useEffect(() => {
+        let live = true;
+        const detach = subscribeFrame(link, 'equipment/point-updated', equipmentFrameSchemas['equipment/point-updated'], frame => {
+            const frameRef = { device: frame.device, group: frame.group, name: frame.name };
+            if (pointKey(frameRef) !== key)
+                return;
+            if (live)
+                setSample({ value: frame.value, time: frame.time });
+        });
+        void link.call('equipment.points.subscribe', { points: [binding] }).catch(() => { });
+        void link.call('equipment.points.read', { points: [binding] })
+            .then(result => {
+            if (!live || !result.ok)
+                return;
+            const first = result.value.samples[0];
+            if (first !== undefined)
+                setSample({ value: first.value, time: first.time });
+        })
+            .catch(() => { });
+        return () => {
+            live = false;
+            detach();
+            void link.call('equipment.points.unsubscribe', { points: [binding] }).catch(() => { });
+        };
+    }, [link, key]);
+    return sample;
+}

package/lib/types/workflows.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The workflow seam: `ctx.workflows` is a generic registry-plus-evaluator —
+ * it knows the mechanism (registration, gating, alerts) and nothing about any
+ * concrete workflow. The gating chain emerges from each occupant's
+ * declarative `requires`; the truth source for satisfaction is the audit
+ * event stream fed back by the layout (`audit.list` on boot/login) and
+ * extended in-session by `announce` after a plugin records an event.
+ *
+ * @module @snap-rail/framework-shadcn/workflows
+ */
+import { Context, type Plugin } from '@snap-rail/cordis';
+import type { ReactNode } from 'react';
+/** How a requirement's event counts as satisfying (who, and when). */
+export type RequirementScope = 'operator-day' | 'day';
+/** One gating declaration: satisfied when a matching event exists. */
+export interface Requirement {
+    /** The audit action that satisfies the requirement. */
+    action: string;
+    /** `operator-day`: the current operator, today. `day`: anyone, today. */
+    scope: RequirementScope;
+}
+/** A sidebar attention effect driven by the workflow owner. */
+export type WorkflowAlert = {
+    kind: 'steady';
+    color: 'red' | 'yellow';
+} | {
+    kind: 'halo';
+    progress: number;
+};
+/** What one workflow contributes at registration. */
+export interface WorkflowDef {
+    /** Stable workflow id (the sidebar and content key). */
+    id: string;
+    /** Sidebar label; locked items render gray with no extra text. */
+    title: string;
+    /** Sidebar ordering; ties break by registration time. */
+    order: number;
+    /** Gating declarations; empty means always unlocked. */
+    requires: readonly Requirement[];
+    render(): ReactNode;
+}
+/** A workflow as the sidebar/content sees it, with derived state. */
+export interface WorkflowEntry extends WorkflowDef {
+    /** Whether the gating declarations are satisfied right now. */
+    unlocked: boolean;
+    /** Whether this workflow is the active content page. */
+    active: boolean;
+    /** The current sidebar attention effect, or `null`. */
+    alert: WorkflowAlert | null;
+}
+/** One business event used for gating evaluation. */
+export interface WorkflowEvent {
+    action: string;
+    actor: string;
+    time: number;
+}
+/** Workflow registry exposed as `ctx.workflows`. */
+export interface WorkflowsService {
+    /** Registered workflows in sidebar order with derived state. */
+    list(): readonly WorkflowEntry[];
+    /** Register one workflow; disposal (caller unload) removes it.
+     * @param caller - owning context; unload drops the workflow.
+     * @param def - the contribution; same-id re-registration replaces.
+     */
+    register(caller: Context, def: WorkflowDef): () => void;
+    /** Make one workflow the active content page. */
+    setActive(id: string): void;
+    /** Set or clear a sidebar attention effect.
+     * @param id - the workflow id.
+     * @param alert - the effect, or `null` to clear.
+     */
+    setAlert(id: string, alert: WorkflowAlert | null): void;
+    /** Set the gating anchor operator (`operator-day` scope re-evaluates). */
+    setOperator(operator: string | null): void;
+    /** Replace the event set (from `audit.list`) and re-evaluate gating. */
+    feedEvents(events: readonly WorkflowEvent[]): void;
+    /** Append one in-session event (after the plugin recorded it host-side).
+     * @param action - the audit action.
+     * @param actor - defaults to the current anchor operator.
+     */
+    announce(action: string, actor?: string): void;
+}
+declare module '@snap-rail/cordis' {
+    interface Context {
+        workflows: WorkflowsService;
+    }
+    interface Events {
+        /** Registry, active page, alert, or gating state changed. */
+        'workflow/changed'(): void;
+    }
+}
+/**
+ * Mounts the `ctx.workflows` registry. All state lives in construction-time
+ * closures: traceable context proxies rebind `this` on every method access,
+ * so `this`-reached state cannot back a service here (the uiSlots lesson).
+ */
+declare const workflowsPlugin: Plugin.Object<void>;
+export default workflowsPlugin;

package/lib/types/workflows.js

@@ -0,0 +1,95 @@
+/**
+ * The workflow seam: `ctx.workflows` is a generic registry-plus-evaluator —
+ * it knows the mechanism (registration, gating, alerts) and nothing about any
+ * concrete workflow. The gating chain emerges from each occupant's
+ * declarative `requires`; the truth source for satisfaction is the audit
+ * event stream fed back by the layout (`audit.list` on boot/login) and
+ * extended in-session by `announce` after a plugin records an event.
+ *
+ * @module @snap-rail/framework-shadcn/workflows
+ */
+import { Context } from '@snap-rail/cordis';
+/** Whether two epoch-ms times fall on the same local calendar day. */
+function sameLocalDay(a, b) {
+    return new Date(a).toDateString() === new Date(b).toDateString();
+}
+/**
+ * Mounts the `ctx.workflows` registry. All state lives in construction-time
+ * closures: traceable context proxies rebind `this` on every method access,
+ * so `this`-reached state cannot back a service here (the uiSlots lesson).
+ */
+const workflowsPlugin = {
+    name: 'client-workflows',
+    apply(ctx) {
+        const workflows = new Map();
+        let nextSeq = 0;
+        let activeId;
+        let operator = null;
+        let events = [];
+        const satisfies = (requirement) => events.some(event => event.action === requirement.action
+            && (requirement.scope === 'day'
+                ? sameLocalDay(event.time, Date.now())
+                : event.actor === operator && sameLocalDay(event.time, Date.now())));
+        const changed = () => {
+            ctx.emit('workflow/changed');
+        };
+        ctx.provide('workflows', {
+            list() {
+                return [...workflows.values()]
+                    .sort((a, b) => a.def.order - b.def.order || a.seq - b.seq)
+                    .map(({ def, alert }) => ({
+                    ...def,
+                    unlocked: def.requires.every(satisfies),
+                    active: def.id === activeId,
+                    alert,
+                }));
+            },
+            register(caller, def) {
+                workflows.set(def.id, { def, alert: null, seq: nextSeq++ });
+                changed();
+                const remove = () => {
+                    if (workflows.delete(def.id)) {
+                        if (activeId === def.id)
+                            activeId = undefined;
+                        changed();
+                    }
+                };
+                // Effects take a body producing the disposer; passing `remove`
+                // itself would run it as setup.
+                caller.effect(() => remove);
+                return remove;
+            },
+            setActive(id) {
+                if (activeId === id)
+                    return;
+                activeId = id;
+                changed();
+            },
+            setAlert(id, alert) {
+                const entry = workflows.get(id);
+                if (entry === undefined || entry.alert === alert)
+                    return;
+                if (alert !== null && alert.kind === 'halo') {
+                    alert = { kind: 'halo', progress: Math.min(1, Math.max(0, alert.progress)) };
+                }
+                entry.alert = alert;
+                changed();
+            },
+            setOperator(next) {
+                if (operator === next)
+                    return;
+                operator = next;
+                changed();
+            },
+            feedEvents(next) {
+                events = [...next].sort((a, b) => a.time - b.time);
+                changed();
+            },
+            announce(action, actor) {
+                events = [...events, { action, actor: actor ?? operator ?? 'client', time: Date.now() }];
+                changed();
+            },
+        });
+    },
+};
+export default workflowsPlugin;