@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/invocation-rule-builder/invocation-rule-builder.types.ts

@@ -0,0 +1,235 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * A single condition within a rule. The field, operator, and value
+ * are all consumer-defined strings — cinder does not interpret them.
+ *
+ * @schemaObject
+ */
+export type InvocationRuleCondition = {
+  /** Identifies the condition row; must be unique within its rule. */
+  id: string;
+  /** The field being tested, e.g. "path" or "label". Consumer-defined. */
+  field: string;
+  /** The comparison operator, e.g. "matches" or "is". Consumer-defined. */
+  operator: string;
+  /** The value being compared against. Consumer-defined. */
+  value: string;
+};
+
+/**
+ * A single action within a rule. The target is a consumer-defined
+ * identifier naming the agent, service, or step to invoke.
+ *
+ * @schemaObject
+ */
+export type InvocationRuleAction = {
+  /** Identifies the action row; must be unique within its rule. */
+  id: string;
+  /** The action target, e.g. a review-agent slug. Consumer-defined. */
+  target: string;
+};
+
+/**
+ * A single automation rule. A rule fires when ALL of its conditions are
+ * met and then triggers all of its actions. Cinder does not execute,
+ * persist, or validate rules — consumers own that logic entirely.
+ *
+ * @schemaObject
+ */
+export type InvocationRule = {
+  /** Unique identifier for the rule. */
+  id: string;
+  /** Display label for the rule. */
+  label: string;
+  /** Zero or more conditions (implicit AND). */
+  conditions: InvocationRuleCondition[];
+  /** Zero or more actions to invoke when conditions match. */
+  actions: InvocationRuleAction[];
+};
+
+/**
+ * An option in a field, operator, or action-target select list.
+ *
+ * @schemaObject
+ */
+export type InvocationRuleOption = {
+  /** The value stored on the condition or action. */
+  value: string;
+  /** The human-readable label shown in the select. */
+  label: string;
+};
+
+/**
+ * Describes the change that caused an `onchange` call.
+ * Consumers use the type to determine what to persist.
+ */
+export type InvocationRuleChange =
+  | { type: 'add-rule'; ruleId: string }
+  | { type: 'rename-rule'; ruleId: string }
+  | { type: 'remove-rule'; ruleId: string }
+  | { type: 'move-rule'; ruleId: string; fromIndex: number; toIndex: number }
+  | { type: 'add-condition'; ruleId: string; conditionId: string }
+  | { type: 'remove-condition'; ruleId: string; conditionId: string }
+  | {
+      type: 'update-condition';
+      ruleId: string;
+      conditionId: string;
+      field: keyof InvocationRuleCondition;
+    }
+  | { type: 'add-action'; ruleId: string; actionId: string }
+  | { type: 'remove-action'; ruleId: string; actionId: string }
+  | { type: 'update-action'; ruleId: string; actionId: string };
+
+/**
+ * Props for the InvocationRuleBuilder component.
+ *
+ * Cinder owns no rule execution, persistence, or validation semantics.
+ * All rule state is managed externally and passed in through the `rules`
+ * prop. Every user action calls `onchange` with the next rule array and
+ * a change descriptor; the consumer decides what to persist.
+ */
+type InvocationRuleBuilderBaseProps = Omit<
+  HTMLAttributes<HTMLElement>,
+  'class' | 'children' | 'onchange'
+> & {
+  /**
+   * The current list of automation rules. Controlled — pass the updated
+   * list returned from `onchange` back into this prop to commit a change.
+   */
+  rules: InvocationRule[];
+
+  /**
+   * Options for the condition field selector. Consumer-provided list of
+   * fields that a condition can test, e.g. "path", "label", "author".
+   */
+  fieldOptions: InvocationRuleOption[];
+
+  /**
+   * Options for the condition operator selector. Consumer-provided list
+   * of operators, e.g. "matches", "is", "is-not", "contains".
+   */
+  operatorOptions: InvocationRuleOption[];
+
+  /**
+   * Options for the action target selector. Consumer-provided list of
+   * targets, e.g. review-agent slugs or step identifiers.
+   */
+  actionOptions: InvocationRuleOption[];
+
+  /**
+   * Label for the "Add rule" button. Defaults to "Add rule".
+   */
+  addRuleLabel?: string;
+
+  /**
+   * Label for the "Add condition" button. Defaults to "Add condition".
+   */
+  addConditionLabel?: string;
+
+  /**
+   * Label for the "Add action" button. Defaults to "Add action".
+   */
+  addActionLabel?: string;
+
+  /** Accessible label for the entire rule builder region. */
+  label?: string;
+
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};
+
+type InvocationRuleBuilderChangeHandler = (
+  nextRules: InvocationRule[],
+  change: InvocationRuleChange,
+) => void;
+
+export type InvocationRuleBuilderProps =
+  | (InvocationRuleBuilderBaseProps & {
+      /**
+       * Called whenever the user makes any edit. Required for editable runtime
+       * usage because editable controls must commit controlled state changes.
+       * Receives the next rule array (pure, not mutated) and a change descriptor.
+       * Consumer owns persistence, validation, and execution.
+       */
+      onchange: InvocationRuleBuilderChangeHandler;
+
+      /**
+       * When false or omitted, renders editable controls. Editable mode requires
+       * `onchange` so controls cannot become interactive-but-no-op.
+       */
+      readonly?: false;
+    })
+  | (InvocationRuleBuilderBaseProps & {
+      /**
+       * Optional in readonly usage because no edit controls are rendered.
+       * Runtime consumers may still pass it when sharing props between modes.
+       */
+      onchange?: InvocationRuleBuilderChangeHandler;
+
+      /**
+       * When true, renders a readonly summary of each rule instead of editable
+       * controls.
+       */
+      readonly: true;
+    });
+
+/**
+ * Cinder-specific schema surface for InvocationRuleBuilder.
+ *
+ * The `onchange` callback is documented but marked unsupported because
+ * functions cannot be represented as JSON Schema controls.
+ */
+export type InvocationRuleBuilderSchemaProps = {
+  /**
+   * The current list of automation rules. Controlled — pass the updated
+   * list returned from `onchange` back into this prop to commit a change.
+   */
+  rules: InvocationRule[];
+
+  /**
+   * Options for the condition field selector. Consumer-provided list of
+   * fields that a condition can test, e.g. "path", "label", "author".
+   */
+  fieldOptions: InvocationRuleOption[];
+
+  /**
+   * Options for the condition operator selector. Consumer-provided list
+   * of operators, e.g. "matches", "is", "is-not", "contains".
+   */
+  operatorOptions: InvocationRuleOption[];
+
+  /**
+   * Options for the action target selector. Consumer-provided list of
+   * targets, e.g. review-agent slugs or step identifiers.
+   */
+  actionOptions: InvocationRuleOption[];
+
+  /**
+   * Must be true for schema-driven usage because editable mode requires
+   * the unsupported `onchange` callback. Runtime consumers may omit this
+   * when passing `onchange` directly.
+   */
+  readonly: true;
+
+  /**
+   * Label for the "Add rule" button. Defaults to "Add rule".
+   */
+  addRuleLabel?: string;
+
+  /**
+   * Label for the "Add condition" button. Defaults to "Add condition".
+   */
+  addConditionLabel?: string;
+
+  /**
+   * Label for the "Add action" button. Defaults to "Add action".
+   */
+  addActionLabel?: string;
+
+  /** Accessible label for the entire rule builder region. */
+  label?: string;
+
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};

package/src/components/invocation-rule-builder/invocation-rule-builder.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/json-schema-editor/composition-branch-keys.ts

@@ -0,0 +1,35 @@
+/**
+ * Stable identity keys for composition branches in property-editor.
+ *
+ * Plain JSON branch values have no built-in identity. If we use the array
+ * index as the {#each} key, removing a non-last branch makes Svelte diff by
+ * index — surviving branches inherit the wrong PropertyEditor instance
+ * (and its local $state). Each PropertyEditor instance keeps its own list
+ * of branch keys parallel to the schema's branch array, and reconciles the
+ * two lengths every render.
+ */
+
+/**
+ * Reconcile a list of stable branch keys with the current branch count.
+ *
+ * - When branches are added beyond the existing key count, append fresh
+ *   keys via `createKey()`.
+ * - When branches are removed (count shrinks), truncate the keys array.
+ * - When the count is unchanged, return the existing keys verbatim.
+ *
+ * @example
+ * const keys = reconcileCompositionBranchKeys(['a'], 3, () => crypto.randomUUID());
+ * // keys is now ['a', '<uuid-1>', '<uuid-2>']
+ */
+export function reconcileCompositionBranchKeys(
+  existingKeys: string[],
+  branchCount: number,
+  createKey: () => string,
+): string[] {
+  // Return the same reference when no change is needed — callers that assign
+  // the result back to $state won't trigger re-renders in that case.
+  if (existingKeys.length === branchCount) return existingKeys;
+  const nextKeys = existingKeys.slice(0, branchCount);
+  while (nextKeys.length < branchCount) nextKeys.push(createKey());
+  return nextKeys;
+}

package/src/components/json-schema-editor/diff-view.svelte

@@ -0,0 +1,39 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import Alert from '../alert/alert.svelte';
+import Button from '../button/button.svelte';
+import DiffViewer from '../diff-viewer/diff-viewer.svelte';
+import EmptyState from '../empty-state/empty-state.svelte';
+let { state, class: className } = $props();
+</script>
+
+<div class={classNames('cinder-jse-diff-view', className)}>
+  {#if state.jsonDraftIsDirty}
+    <Alert variant="warning">
+      <p>The diff shows the committed state; uncommitted JSON edits are not included.</p>
+      <div class="cinder-jse-dirty-actions">
+        <Button variant="primary" size="sm" onclick={() => state.applyJsonDraft()}>
+          Apply JSON
+        </Button>
+        <Button variant="secondary" size="sm" onclick={() => state.discardJsonDraft()}>
+          Discard JSON
+        </Button>
+      </div>
+    </Alert>
+  {/if}
+
+  {#if !state.hasChanges}
+    <EmptyState title="No changes yet" description="Edit the schema to see a diff here." />
+  {:else}
+    <DiffViewer
+      original={state.diffOriginal}
+      current={state.diffCurrent}
+      normalizeInputs={false}
+      readonly
+    />
+  {/if}
+</div>

package/src/components/json-schema-editor/form-view.svelte

@@ -0,0 +1,50 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import Alert from '../alert/alert.svelte';
+import Button from '../button/button.svelte';
+import EmptyState from '../empty-state/empty-state.svelte';
+import PropertyEditor from './property-editor.svelte';
+let { state, idPrefix, onvalidationerrorcount, class: className } = $props();
+// Snapshot the committed schema each render so changes propagate via the
+// value prop on PropertyEditor. We don't pass the live committed schema by
+// reference; PropertyEditor produces a brand-new object on each commit.
+const rootSchema = $derived(state.committedSchema);
+</script>
+
+<div class={classNames('cinder-jse-form-view', className)}>
+  {#if state.jsonDraftIsDirty}
+    <Alert variant="warning">
+      <p>The JSON view has uncommitted changes. Apply or discard them to edit in the form.</p>
+      <div class="cinder-jse-dirty-actions">
+        <Button variant="primary" size="sm" onclick={() => state.applyJsonDraft()}>
+          Apply JSON
+        </Button>
+        <Button variant="secondary" size="sm" onclick={() => state.discardJsonDraft()}>
+          Discard JSON
+        </Button>
+      </div>
+    </Alert>
+  {/if}
+
+  {#if rootSchema === null}
+    <EmptyState
+      title="Schema not loaded"
+      description={state.originalLoadError ??
+        'The current input could not be parsed. Edit the JSON view to set a valid schema.'}
+    />
+  {:else}
+    <PropertyEditor
+      {idPrefix}
+      path=""
+      depth={0}
+      readonly={state.readonly || state.jsonDraftIsDirty}
+      value={rootSchema}
+      {onvalidationerrorcount}
+      onchange={(next, options) => state.commitFromForm(next, options)}
+    />
+  {/if}
+</div>

package/src/components/json-schema-editor/index.ts

@@ -0,0 +1,19 @@
+import './json-schema-editor.css';
+import JsonSchemaEditor from './json-schema-editor.svelte';
+
+export default JsonSchemaEditor;
+export type {
+  JsonSchemaDraft,
+  JsonSchemaEditorChangeEvent,
+  JsonSchemaEditorMode,
+  JsonSchemaEditorProps,
+  JsonSchemaEditorRevertEvent,
+  JsonSchemaEditorView,
+  JsonSchemaKnownDraft,
+  JsonSchemaTypeName,
+  JsonSchemaValidationError,
+  JsonSchemaValidationResult,
+  JsonSchemaValidationStatus,
+  JsonSchemaValue,
+} from './json-schema-editor.types.ts';
+export { JsonSchemaEditor };

package/src/components/json-schema-editor/json-schema-editor-impl.svelte

@@ -0,0 +1,212 @@
+<script lang="ts" module>
+/**
+ * Mac detection for keyboard-shortcut routing. `navigator.platform` is
+ * deprecated; prefer `navigator.userAgentData?.platform` and fall back to
+ * `platform` only when the modern accessor is unavailable (Firefox, Safari).
+ * Hoisted out of the keydown handler so it isn't re-evaluated per keystroke.
+ */
+function detectMacPlatform() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const navigatorWithUserAgentData = navigator;
+    const modernPlatform = navigatorWithUserAgentData.userAgentData?.platform;
+    if (typeof modernPlatform === 'string' && modernPlatform.length > 0) {
+        return /Mac/.test(modernPlatform);
+    }
+    return /Mac/.test(navigator.platform);
+}
+const isMacPlatform = detectMacPlatform();
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+import { useAnnouncer } from '../../utilities/use-announcer.svelte.ts';
+import Badge from '../badge/badge.svelte';
+import Tab from '../tab/tab.svelte';
+import TabList from '../tab-list/tab-list.svelte';
+import TabPanel from '../tab-panel/tab-panel.svelte';
+import Tabs from '../tabs/tabs.svelte';
+import DiffView from './diff-view.svelte';
+import FormView from './form-view.svelte';
+import { createEditorState } from './json-schema-editor-state.svelte.ts';
+import JsonSchemaToolbar from './json-schema-toolbar.svelte';
+import JsonView from './json-view.svelte';
+let { id, schema, original, schemaKey, view = $bindable('form'), readonly = false, maxHistory, draftOverride, onchange, onrevert, onvalidate, class: className, } = $props();
+const announcer = useAnnouncer();
+// Build state container once. Schema reloads happen via `schemaKey`. Other
+// mutable props (readonly, draftOverride, callback handlers) are kept in
+// sync after mount via the $effects below — without that, parents passing
+// inline lambdas would have their handlers captured stale at construction.
+// The container is built exactly once; read the seed props untracked so this
+// construction never becomes a reactive dependency. Later prop changes are
+// applied through the $effects below (readonly/draftOverride) and schemaKey.
+const stateOptions = untrack(() => {
+    const options = {
+        schema,
+        readonly,
+        onchange: (event) => onchange?.(event),
+        onrevert: (event) => onrevert?.(event),
+        onvalidate: (result) => onvalidate?.(result),
+    };
+    if (original !== undefined)
+        options.original = original;
+    if (maxHistory !== undefined)
+        options.maxHistory = maxHistory;
+    if (draftOverride !== undefined)
+        options.draftOverride = draftOverride;
+    return options;
+});
+let localValidationErrorCount = $state(0);
+const editorState = createEditorState(stateOptions);
+const toolbarValidationErrorCount = $derived(view === 'form' ? localValidationErrorCount : 0);
+// Sync `readonly` into the state container whenever the prop changes.
+// `setReadonly` only assigns the flag, so re-applying the construction-seeded
+// value on the initial effect run is a harmless no-op — no sentinel needed.
+$effect(() => {
+    editorState.setReadonly(readonly);
+});
+// Sync `draftOverride` into the state container when the *prop* changes.
+// Unlike `setReadonly`, `setDraftOverride` re-runs validation and emits an
+// `onvalidate` event, so we must skip the initial effect run (the value was
+// already seeded at construction) to avoid a spurious mount-time validation
+// emit. The sentinel detects a genuine prop transition; it is not guarding a
+// reactive loop — the setter writes closure-private state, never back to the
+// `draftOverride` prop.
+let lastDraftOverride = untrack(() => draftOverride);
+$effect(() => {
+    if (draftOverride !== lastDraftOverride) {
+        lastDraftOverride = draftOverride;
+        editorState.setDraftOverride(draftOverride);
+    }
+});
+// Tear down debounce timers on unmount so stale callbacks don't fire after
+// the parent unmounts the editor.
+$effect(() => {
+    return () => editorState.destroy();
+});
+// schemaKey-triggered reset. Track the previous key explicitly so we don't
+// reload on initial mount (state was already seeded above) or on re-renders
+// that don't change the key. Only `schemaKey` is a tracked dependency — the
+// documented contract is "change schemaKey to reset". `schema`/`original` are
+// read untracked so a parent live-patching those props (without changing the
+// key) does not silently re-run this effect; when the key *does* change we
+// still read their current values fresh inside the untracked block.
+let lastSchemaKey = untrack(() => schemaKey);
+$effect(() => {
+    if (schemaKey !== lastSchemaKey) {
+        lastSchemaKey = schemaKey;
+        untrack(() => {
+            editorState.reload(schema, original);
+        });
+        announcer.announce('Schema reloaded');
+    }
+});
+// Sync the bindable `view` prop into `editorState.view`. The flow is intentionally
+// one-directional: `view` is the single source of truth. The parent's
+// `bind:view` and the `Tabs` `bind:value={view}` both write the prop directly,
+// and `state` never changes its view autonomously (`reload()` does not touch
+// `view`), so there is no state→prop direction to mirror. A write-back effect
+// that mirrored `editorState.view` onto the prop would force an extra render of the
+// tab tree on every unrelated state change; if a future code path ever mutates
+// `editorState.view` independently, that path must also update the `view` prop (or
+// expose an onViewChange callback) rather than rely on a mirror effect here.
+$effect(() => {
+    if (editorState.view !== view)
+        editorState.setView(view);
+});
+// Action handlers used by the toolbar.
+function handleUndo() {
+    const label = editorState.undo();
+    announcer.announce(label ? `Undid: ${label}` : 'Undid last edit');
+}
+function handleRedo() {
+    const label = editorState.redo();
+    announcer.announce(label ? `Redid: ${label}` : 'Redid edit');
+}
+function handleRevert() {
+    editorState.revert();
+    announcer.announce('Reverted to original schema');
+}
+// Editor-level keyboard shortcuts: only fire when focus isn't inside an
+// editable element so native text undo continues to work in inputs.
+function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+        return true;
+    return target.isContentEditable;
+}
+function onKeyDown(event) {
+    const meta = isMacPlatform ? event.metaKey : event.ctrlKey;
+    if (!meta)
+        return;
+    if (isEditableTarget(event.target))
+        return;
+    const key = event.key.toLowerCase();
+    if (key === 'z' && !event.shiftKey) {
+        event.preventDefault();
+        handleUndo();
+    }
+    else if ((key === 'z' && event.shiftKey) || key === 'y') {
+        event.preventDefault();
+        handleRedo();
+    }
+}
+</script>
+
+<!--
+  The keydown handler implements editor-wide undo/redo shortcuts (Cmd/Ctrl+Z,
+  Shift+Z, Y). It listens on the region landmark and acts on keystrokes that
+  bubble up from the focusable editor surfaces (form fields, JSON textarea,
+  diff view) inside it, so the noninteractive-element-interactions rule is a
+  false positive — `role="region"` is the correct landmark for the editor.
+-->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+  {id}
+  class={classNames('cinder-jse', className)}
+  data-cinder-jse=""
+  onkeydown={onKeyDown}
+  role="region"
+  aria-label="JSON Schema editor"
+>
+  <JsonSchemaToolbar
+    state={editorState}
+    localValidationErrorCount={toolbarValidationErrorCount}
+    onUndo={handleUndo}
+    onRedo={handleRedo}
+    onRevert={handleRevert}
+  />
+
+  <Tabs bind:value={view}>
+    <TabList label="Editor view">
+      <Tab value="form">Form</Tab>
+      <Tab value="json">JSON</Tab>
+      <Tab value="diff">
+        Diff{#if editorState.hasChanges}<span class="cinder-sr-only">, has changes</span>{/if}
+        {#snippet trailing()}
+          {#if editorState.hasChanges}
+            <Badge variant="neutral" aria-hidden="true">●</Badge>
+          {/if}
+        {/snippet}
+      </Tab>
+    </TabList>
+
+    <TabPanel value="form">
+      <FormView
+        state={editorState}
+        idPrefix={`${id}-form`}
+        onvalidationerrorcount={(count) => (localValidationErrorCount = count)}
+      />
+    </TabPanel>
+    <TabPanel value="json">
+      <JsonView state={editorState} idPrefix={`${id}-json`} />
+    </TabPanel>
+    <TabPanel value="diff">
+      <DiffView state={editorState} />
+    </TabPanel>
+  </Tabs>
+</div>