@tasker-systems/temper-design 0.0.0-stage → 0.6.3

package/contract/theme.schema.json

@@ -0,0 +1,444 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/tasker-systems/temper/packages/temper-design/contract/theme.schema.json",
+  "title": "temper theme",
+  "description": "A theme is data: values for every role in the contract. Components consume roles, never values; a theme that omits a role or invents one does not validate.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "name",
+    "title",
+    "version",
+    "appearance",
+    "tokens"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "kind": {
+      "const": "theme"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Stable identifier; also the value of data-theme."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string"
+    },
+    "appearance": {
+      "enum": [
+        "dark",
+        "light"
+      ],
+      "description": "Sets color-scheme; selects this theme when the system appearance matches and the person follows it."
+    },
+    "counterpart": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The theme of the opposite appearance that pairs with this one."
+    },
+    "provenance": {
+      "type": "string",
+      "description": "Where the values came from."
+    },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "color",
+        "font",
+        "radius",
+        "motion",
+        "tracking"
+      ],
+      "properties": {
+        "color": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ground",
+            "surface",
+            "surface-raised",
+            "overlay",
+            "text",
+            "text-muted",
+            "text-subtle",
+            "text-faint",
+            "rule",
+            "rule-strong",
+            "accent",
+            "accent-muted",
+            "accent-line",
+            "accent-line-soft",
+            "accent-wash",
+            "accent-hover",
+            "on-accent",
+            "focus",
+            "notice",
+            "notice-wash",
+            "success",
+            "success-wash",
+            "danger",
+            "danger-wash",
+            "pending",
+            "pending-wash",
+            "region-arriving",
+            "region-arriving-wash",
+            "region-empty",
+            "region-empty-wash",
+            "region-gave-up",
+            "region-gave-up-wash",
+            "region-failed",
+            "region-failed-wash",
+            "author-human",
+            "author-agent",
+            "cat-1",
+            "cat-2",
+            "cat-3",
+            "cat-4",
+            "cat-5",
+            "cat-6",
+            "cat-7",
+            "cat-8",
+            "cat-neutral",
+            "code-key",
+            "code-string",
+            "code-number",
+            "code-comment"
+          ],
+          "properties": {
+            "ground": {
+              "$ref": "#/$defs/color",
+              "description": "The page/window ground. Everything else is composited over it."
+            },
+            "surface": {
+              "$ref": "#/$defs/color",
+              "description": "Panels, cards, docked peeks \u2014 a lifted fill over ground."
+            },
+            "surface-raised": {
+              "$ref": "#/$defs/color",
+              "description": "Popovers, menus, the command palette \u2014 one step above surface."
+            },
+            "overlay": {
+              "$ref": "#/$defs/color",
+              "description": "Scrim behind a modal. Translucent."
+            },
+            "text": {
+              "$ref": "#/$defs/color",
+              "description": "Primary reading text. Floor: 7:1 on ground and surface."
+            },
+            "text-muted": {
+              "$ref": "#/$defs/color",
+              "description": "Secondary text \u2014 decks, body in dense chrome. Floor: 4.5:1."
+            },
+            "text-subtle": {
+              "$ref": "#/$defs/color",
+              "description": "Tertiary text \u2014 mono labels, metadata strips, counts. Floor: 4.5:1."
+            },
+            "text-faint": {
+              "$ref": "#/$defs/color",
+              "description": "Disabled and decorative only; never carries information. Floor: 2.5:1."
+            },
+            "rule": {
+              "$ref": "#/$defs/color",
+              "description": "Hairline dividers."
+            },
+            "rule-strong": {
+              "$ref": "#/$defs/color",
+              "description": "Dividers that must survive a busy surface; input outlines."
+            },
+            "accent": {
+              "$ref": "#/$defs/color",
+              "description": "The single accent: section labels, the rail, links, primary actions. Floor: 4.5:1."
+            },
+            "accent-muted": {
+              "$ref": "#/$defs/color",
+              "description": "Accent at rest where full accent would shout (secondary links, idle markers)."
+            },
+            "accent-line": {
+              "$ref": "#/$defs/color",
+              "description": "Accent borders on buttons and focused inputs."
+            },
+            "accent-line-soft": {
+              "$ref": "#/$defs/color",
+              "description": "The rail motif and soft accent borders."
+            },
+            "accent-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Selected-row / active-chip fill."
+            },
+            "accent-hover": {
+              "$ref": "#/$defs/color",
+              "description": "Hover fill on accent affordances."
+            },
+            "on-accent": {
+              "$ref": "#/$defs/color",
+              "description": "Text on a solid accent fill. Floor: 4.5:1 on accent."
+            },
+            "focus": {
+              "$ref": "#/$defs/color",
+              "description": "Keyboard focus ring. Floor: 3:1 on ground."
+            },
+            "notice": {
+              "$ref": "#/$defs/color",
+              "description": "A condition that wants the reader's attention (not a failure). Floor: 4.5:1 on its wash."
+            },
+            "notice-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind a notice."
+            },
+            "success": {
+              "$ref": "#/$defs/color",
+              "description": "A completed act confirmed. Floor: 4.5:1 on its wash."
+            },
+            "success-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind a success note."
+            },
+            "danger": {
+              "$ref": "#/$defs/color",
+              "description": "Destructive affordances (delete, retract). Floor: 4.5:1 on its wash."
+            },
+            "danger-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind a destructive confirmation."
+            },
+            "pending": {
+              "$ref": "#/$defs/color",
+              "description": "Pending state \u2014 proposals awaiting ratification, threads addressed to you. State, not alarm. Floor: 4.5:1 on its wash."
+            },
+            "pending-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind pending items."
+            },
+            "region-arriving": {
+              "$ref": "#/$defs/color",
+              "description": "Region state: a read in flight. Floor: 4.5:1 on its wash."
+            },
+            "region-arriving-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind an arriving region."
+            },
+            "region-empty": {
+              "$ref": "#/$defs/color",
+              "description": "Region state: the read succeeded and there is nothing. Floor: 4.5:1 on its wash."
+            },
+            "region-empty-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind an empty region."
+            },
+            "region-gave-up": {
+              "$ref": "#/$defs/color",
+              "description": "Region state: the system stopped waiting. A hue nothing else uses. Floor: 4.5:1 on its wash."
+            },
+            "region-gave-up-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind a gave-up region."
+            },
+            "region-failed": {
+              "$ref": "#/$defs/color",
+              "description": "Region state: the read failed. Floor: 4.5:1 on its wash."
+            },
+            "region-failed-wash": {
+              "$ref": "#/$defs/color",
+              "description": "Fill behind a failed region."
+            },
+            "author-human": {
+              "$ref": "#/$defs/color",
+              "description": "Authorship gutter mark for a person. Floor: 3:1 on ground."
+            },
+            "author-agent": {
+              "$ref": "#/$defs/color",
+              "description": "Authorship gutter mark for an agent acting on someone's behalf. Floor: 3:1 on ground."
+            },
+            "cat-1": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 1 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-2": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 2 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-3": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 3 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-4": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 4 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-5": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 5 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-6": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 6 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-7": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 7 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-8": {
+              "$ref": "#/$defs/color",
+              "description": "Categorical slot 8 of 8. Vocabularies — core's doc types and plugins' — bind their terms to slots; they never name colours. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "cat-neutral": {
+              "$ref": "#/$defs/color",
+              "description": "The categorical mark bound to no slot: a doc type no vocabulary binds, or a tint deliberately unnamed. Floor: 4.5:1 on ground, surface and surface-raised."
+            },
+            "code-key": {
+              "$ref": "#/$defs/color",
+              "description": "Syntax: keys, attributes, names. Floor: 4.5:1 on surface."
+            },
+            "code-string": {
+              "$ref": "#/$defs/color",
+              "description": "Syntax: strings. Floor: 4.5:1 on surface."
+            },
+            "code-number": {
+              "$ref": "#/$defs/color",
+              "description": "Syntax: numbers, literals, keywords. Floor: 4.5:1 on surface."
+            },
+            "code-comment": {
+              "$ref": "#/$defs/color",
+              "description": "Syntax: comments. Floor: 4.5:1 on surface."
+            }
+          }
+        },
+        "font": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "reading",
+            "doing",
+            "ui"
+          ],
+          "properties": {
+            "reading": {
+              "$ref": "#/$defs/fontStack",
+              "description": "Reading face \u2014 prose, headings, decks."
+            },
+            "doing": {
+              "$ref": "#/$defs/fontStack",
+              "description": "Doing face \u2014 labels, commands, code, metadata."
+            },
+            "ui": {
+              "$ref": "#/$defs/fontStack",
+              "description": "Dense UI face \u2014 grids, form controls."
+            }
+          }
+        },
+        "radius": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "chip",
+            "panel"
+          ],
+          "properties": {
+            "chip": {
+              "$ref": "#/$defs/length",
+              "description": "Chips, code blocks, inputs."
+            },
+            "panel": {
+              "$ref": "#/$defs/length",
+              "description": "Panels and cards. The editorial default is 0."
+            }
+          }
+        },
+        "motion": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "quick",
+            "settle",
+            "easing"
+          ],
+          "properties": {
+            "quick": {
+              "$ref": "#/$defs/duration",
+              "description": "Hover/colour transitions."
+            },
+            "settle": {
+              "$ref": "#/$defs/duration",
+              "description": "Panel slide-in, tier fades."
+            },
+            "easing": {
+              "type": "string",
+              "pattern": "^(ease|ease-in|ease-out|ease-in-out|linear|cubic-bezier\\([^)]*\\))$",
+              "description": "The one easing curve."
+            }
+          }
+        },
+        "tracking": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "label",
+            "strip",
+            "eyebrow",
+            "ui",
+            "mark"
+          ],
+          "properties": {
+            "label": {
+              "$ref": "#/$defs/em",
+              "description": "Section labels."
+            },
+            "strip": {
+              "$ref": "#/$defs/em",
+              "description": "Metadata strips."
+            },
+            "eyebrow": {
+              "$ref": "#/$defs/em",
+              "description": "Hero eyebrows."
+            },
+            "ui": {
+              "$ref": "#/$defs/em",
+              "description": "Buttons, nav."
+            },
+            "mark": {
+              "$ref": "#/$defs/em",
+              "description": "Wordmark."
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "color": {
+      "type": "string",
+      "pattern": "^(#[0-9a-fA-F]{6}|rgba\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*(0|1|0?\\.\\d+)\\s*\\))$",
+      "description": "#rrggbb or rgba(r, g, b, a). No named colours, no hsl \u2014 the contrast check reads these."
+    },
+    "fontStack": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A CSS font-family list. Fonts are bundled by each surface, never fetched \u2014 a surface must be able to render offline."
+    },
+    "length": {
+      "type": "string",
+      "pattern": "^(0|\\d+(\\.\\d+)?(px|rem))$"
+    },
+    "duration": {
+      "type": "string",
+      "pattern": "^\\d+ms$"
+    },
+    "em": {
+      "type": "string",
+      "pattern": "^-?\\d*\\.?\\d+em$"
+    }
+  }
+}

package/dist/graph.d.ts

@@ -0,0 +1,191 @@
+import { type SimulationNodeDatum } from 'd3-force';
+export type GraphLayout = 'force' | 'radial';
+export interface LayoutInput {
+    id: string;
+    /** In a radial layout, a core node settles at the centre and the rest ring it. */
+    core?: boolean;
+}
+export interface Placed extends SimulationNodeDatum {
+    id: string;
+    /** Distinct neighbours among the placed nodes. */
+    degree: number;
+    x: number;
+    y: number;
+}
+/**
+ * Every edge between one pair of nodes, drawn as one line. Edges are kept in the order they came,
+ * oriented from `source` to `target`: an edge that runs the other way is `reversed`.
+ */
+export interface Joined<E> {
+    edges: {
+        edge: E;
+        reversed: boolean;
+    }[];
+    source: Placed;
+    target: Placed;
+}
+/** The space the simulation runs in. A surface sizes it to its canvas. */
+export interface Plane {
+    width: number;
+    height: number;
+}
+export declare const DEFAULT_PLANE: Plane;
+/** A mark's radius: more connected, a little larger, and never past a bound. */
+export declare const nodeRadius: (degree: number) => number;
+/**
+ * How many other carried nodes each node is joined to. Neighbours, not edges: two relations
+ * between the same pair are one line, and a node joined only to itself has none.
+ */
+export declare function degrees(nodes: {
+    id: string;
+}[], edges: {
+    source: string;
+    target: string;
+}[]): Map<string, number>;
+export interface Settled<E> {
+    nodes: Placed[];
+    edges: Joined<E>[];
+    selfJoined: E[];
+    unconnected: string[];
+    /** Whether the radial force ran: asked for, and the placed nodes held both core and ring. */
+    radial: boolean;
+}
+/** Settles the connected nodes; see the module header for the policy. */
+export declare function settle<E extends {
+    source: string;
+    target: string;
+}>(input: LayoutInput[], edges: E[], layout: GraphLayout, plane?: Plane): Settled<E>;
+export interface Box {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Truncate to `max` characters (code points, so no character is split) with a trailing ellipsis. */
+export declare const truncate: (text: string, max: number) => string;
+export interface Caption {
+    id: string;
+    x: number;
+    y: number;
+    text: string;
+}
+export interface CaptionOptions {
+    /** How many captions to try to draw at all, most connected first. A surface's room. */
+    max: number;
+    /** Approximate advance width of one character at the render font size. */
+    charWidth: number;
+    lineHeight: number;
+    /** Longest caption, in characters, before the ellipsis. */
+    cap: number;
+    /** Clearance around each reserved box. */
+    padding: number;
+}
+export declare const CAPTION: CaptionOptions;
+/**
+ * Which captions can be drawn without landing on another caption or on another node's mark.
+ * Greedy, most connected first, ties broken by code-unit order on id. A caption that would collide
+ * is dropped, not nudged: a label moved off its node reads as belonging to whatever it landed
+ * near. Every node is still drawn and still named elsewhere (a tooltip, a hover card, a list).
+ */
+export declare function placeCaptions(nodes: {
+    id: string;
+    x: number;
+    y: number;
+    degree: number;
+    label: string;
+}[], options?: Partial<CaptionOptions>): Caption[];
+/**
+ * The drawing's frame: every mark and caption, with a margin. A surface that fits its viewBox to
+ * the drawing reads it; one with a fixed canvas does not need it. Captions are measured with the
+ * same options `placeCaptions` was given, so the frame fits what was placed.
+ */
+export declare function frame(nodes: Placed[], captions: Caption[], { margin, plane, caption, }?: {
+    margin?: number;
+    plane?: Plane;
+    caption?: Partial<CaptionOptions>;
+}): Box;
+/** How far from its centre a line ends at a mark: just past the mark's own rim. */
+export declare const rimOf: (degree: number) => number;
+/**
+ * A pair's line, trimmed to the rims of its two marks, and an arrowhead at each end an edge
+ * points to. Heads are shapes, not SVG markers, so a drawing holds no ids and any number of
+ * graphs share a page. A line run centre to centre beneath its marks would end every head under
+ * the node it points at. `rims` overrides where each end stops, for a mark that is not a circle.
+ */
+export declare function edgeGeometry(source: Placed, target: Placed, ends: {
+    atSource: boolean;
+    atTarget: boolean;
+}, rims?: {
+    source: number;
+    target: number;
+}): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    heads: string[];
+};
+export type EdgeKind = 'contains' | 'leads_to' | 'express' | 'near';
+/**
+ * What the grammar reads off an edge: the relation's label, kind, polarity and weight. Every
+ * field is optional, because a read may not carry it; each absence draws a stated default.
+ */
+export interface Answered {
+    /** The relation, as the corpus names it. */
+    label?: string | null;
+    edgeKind?: EdgeKind;
+    polarity?: 'forward' | 'inverse';
+    /**
+     * The relation's strength, drawn as the line's width. Absent draws the unweighted width —
+     * never a default of 1, which is a real weight.
+     */
+    weight?: number | null;
+}
+export type StrokeRole = 'structural' | 'derived' | 'contradicts';
+/**
+ * Stroke for an edge whose weight is absent. A width cannot say "not reported" by itself, so a
+ * surface names the weight, or its absence, where it names the relation.
+ */
+export declare const UNWEIGHTED_WIDTH = 1.4;
+/**
+ * Weight → width over the range weights take: asserted at 1.0 by default and only lowered by
+ * decay, so (0, 1] spans 1 to 2.5. A weight outside it is held to the bounds, so a stray value
+ * cannot draw a line that dominates the drawing.
+ */
+export declare const widthOf: (weight: number) => number;
+/** How one edge draws: its role (painted by `contract/graph.css`), dash, width, and heads. */
+export interface Stroke {
+    role: StrokeRole;
+    dash: string | null;
+    width: number;
+    atSource: boolean;
+    atTarget: boolean;
+    /**
+     * A cross at the midpoint: contradicts' channel beyond colour. Its role sits too close to the
+     * structural one in luminance for a colour-blind reader, and dash (kind) and width (weight) are
+     * taken, so it carries a shape of its own.
+     */
+    cross: boolean;
+}
+export declare function stroke(edge: Answered): Stroke;
+/** Where a pair's arrowheads go: at each end some edge between them points to. */
+export declare function pairEnds<E extends Answered>(edges: {
+    edge: E;
+    reversed: boolean;
+}[]): {
+    atSource: boolean;
+    atTarget: boolean;
+};
+/**
+ * How a pair's line is drawn when its edges differ: a contradiction is never hidden behind a
+ * plainer relation, a line dashes only when every edge on it dashes — with the dash the first
+ * dashing edge names — and it is never thinner than the heaviest relation on it.
+ */
+export declare function pairStroke<E extends Answered>(edges: {
+    edge: E;
+}[]): {
+    role: StrokeRole;
+    dash: string | null;
+    width: number;
+    cross: boolean;
+};