@514sid/signagekit 0.0.0-stage → 0.0.2

package/dist/types/types.d.ts

@@ -0,0 +1,271 @@
+import type { Colors } from './colors';
+/** A literal, or a pointer into the data, like { "bind": "/menu/0/price" }. */
+export type Bind = {
+    bind: string;
+    /** Shown when the path is missing or empty in the data. */
+    fallback?: string | number;
+};
+export type Value = string | number | Bind;
+export type Surface = 'base' | 'raised' | 'accent';
+export type Align = 'start' | 'center' | 'end';
+export type TextSize = 's' | 'm' | 'l' | 'xl';
+interface Base {
+    surface?: Surface;
+    /** Short label shown above the component, like "Menu" or "Wait time". */
+    title?: Value;
+    /** Pins the text size in px on the reference canvas, skipping fitting. */
+    size?: number | TextSize;
+    /** Share of a stack's space, relative to its siblings. Default 1. */
+    weight?: number;
+    /** A named icon shown before the title, in place of the square marker. */
+    icon?: string;
+}
+export interface Heading extends Base {
+    type: 'heading';
+    text: Value;
+    align?: Align;
+}
+export interface Text extends Base {
+    type: 'text';
+    text: Value;
+    size?: TextSize;
+    align?: Align;
+    fit?: boolean;
+}
+export type State = 'neutral' | 'good' | 'warning' | 'danger';
+/**
+ * Sets the state from the value, so data only has to carry numbers. With
+ * danger above warning, higher is worse; with danger below, lower is worse.
+ */
+export interface Thresholds {
+    warning?: number;
+    danger?: number;
+}
+export interface Stat extends Base {
+    type: 'stat';
+    value: Value;
+    label?: Value;
+    unit?: Value;
+    /** Bound or literal; anything but good, warning or danger is neutral. */
+    state?: Value;
+    /** up, down or flat; bound or literal. Anything else shows no arrow. */
+    trend?: Value;
+    /** Change shown next to the arrow, like "+4.2%". */
+    delta?: Value;
+    /** Which direction is good news; colors the arrow green or red. */
+    good_when?: 'up' | 'down';
+    /** compact (default) shortens numbers from 10,000 up; full never does. */
+    format?: 'compact' | 'full';
+    /** false keeps this stat's own size instead of matching its row. */
+    match_row?: boolean;
+    /** Recent values drawn as a sparkline under the number. */
+    spark?: Value[] | Bind;
+    thresholds?: Thresholds;
+}
+export interface Table extends Base {
+    type: 'table';
+    columns: string[];
+    rows: Value[][] | Bind;
+    align?: Align[];
+    /** Rows per page; pages flip instantly every `seconds`. */
+    page_rows?: number;
+    /** Relative column widths, like [3, 1, 1]. Long cells end in an ellipsis. */
+    widths?: number[];
+    seconds?: number;
+}
+export interface List extends Base {
+    type: 'list';
+    items: Value[] | Bind;
+}
+export interface Image extends Base {
+    type: 'image';
+    src: Value;
+    fit?: 'cover' | 'contain';
+    alt?: string;
+}
+export interface Clock extends Base {
+    type: 'clock';
+    hour12?: boolean;
+    show_date?: boolean;
+}
+export interface Countdown extends Base {
+    type: 'countdown';
+    to: Value;
+    label?: Value;
+    /** Shown once the time has passed. Default "Now". */
+    done?: Value;
+}
+export interface ChartSeries {
+    name: Value;
+    values: Value[] | Bind;
+}
+/** Line, area or column chart, drawn by uPlot. */
+export interface Chart extends Base {
+    type: 'chart';
+    kind: 'line' | 'area' | 'column';
+    labels: Value[] | Bind;
+    series: ChartSeries[];
+    /** A horizontal target line, like an SLO or a production goal. */
+    target?: Value;
+    target_label?: Value;
+    /** Fixed y-axis range; either end can be left out. */
+    y_min?: number;
+    y_max?: number;
+}
+/** Shows one message at a time and swaps to the next instantly. */
+export interface Cycle extends Base {
+    type: 'cycle';
+    items: Value[] | Bind;
+    seconds?: number;
+    align?: Align;
+}
+export interface Stack extends Base {
+    type: 'stack';
+    direction?: 'row' | 'column';
+    items: Component[];
+}
+export type Component = Heading | Text | Stat | Table | List | Image | Clock | Countdown | Cycle | Chart | Stack | Meter | Meters | Bars | Split | Status | Schedule | Queue | Clocks | Slideshow | Qr;
+/** A labelled amount, used by meters, bars and split. */
+export interface Part {
+    label: Value;
+    value: Value;
+    max?: Value;
+    state?: Value;
+}
+export type Parts = Part[] | Bind;
+/** One value against a limit. */
+export interface Meter extends Base {
+    type: 'meter';
+    value: Value;
+    max?: Value;
+    label?: Value;
+    unit?: Value;
+    state?: Value;
+    thresholds?: Thresholds;
+}
+/** Several meters, one row each, bars aligned. */
+export interface Meters extends Base {
+    type: 'meters';
+    items: Parts;
+    max?: Value;
+    unit?: Value;
+    /** Applied to each row without its own state. */
+    thresholds?: Thresholds;
+}
+/** Ranked horizontal bars, largest first. */
+export interface Bars extends Base {
+    type: 'bars';
+    items: Parts;
+    unit?: Value;
+    limit?: number;
+}
+/** One whole split into up to six parts. */
+export interface Split extends Base {
+    type: 'split';
+    items: Parts;
+}
+/** Rows with a state icon each, like service health. */
+export interface Status extends Base {
+    type: 'status';
+    items: {
+        label: Value;
+        state: Value;
+        note?: Value;
+    }[] | Bind;
+}
+/** Time-ordered entries; the current and next ones are marked. */
+export interface Schedule extends Base {
+    type: 'schedule';
+    items: {
+        start: Value;
+        end?: Value;
+        title: Value;
+        detail?: Value;
+    }[] | Bind;
+    rows?: number;
+}
+/** "Now serving" number with the recently called ones. */
+export interface Queue extends Base {
+    type: 'queue';
+    current: Value;
+    recent?: Value[] | Bind;
+    label?: Value;
+}
+/** Several clocks, one per time zone. */
+export interface Clocks extends Base {
+    type: 'clocks';
+    /** `zone` is the older name for `timezone` and still works. */
+    zones: {
+        label: Value;
+        timezone?: string;
+        zone?: string;
+    }[];
+    hour12?: boolean;
+}
+/** Images that swap instantly on a timer. */
+export interface Slideshow extends Base {
+    type: 'slideshow';
+    images: Value[] | Bind;
+    seconds?: number;
+    fit?: 'cover' | 'contain';
+}
+/** QR code, black on white for scanners, with an optional caption. */
+export interface Qr extends Base {
+    type: 'qr';
+    value: Value;
+    label?: Value;
+}
+export type ComponentType = Component['type'];
+/** A fixed grid: named areas, like CSS grid-template-areas. */
+export interface GridLayout {
+    areas: string[];
+    columns?: string;
+    rows?: string;
+    gap?: number;
+}
+/** One zone in a flow layout. */
+export interface FlowItem {
+    zone: string;
+    /** Columns out of 12 in the design orientation. Default 12. */
+    span?: number;
+    /** A number is a share of the free height (like fr); "150px" is fixed. */
+    height?: number | string;
+}
+/** Zones in reading order, packed into rows to suit the screen's shape. */
+export interface FlowLayout {
+    flow: (string | FlowItem)[];
+    design?: 'landscape' | 'portrait';
+    gap?: number;
+}
+export type Layout = GridLayout | FlowLayout;
+/**
+ * A screen-wide message: full screen (takeover) or a strip across the top
+ * (banner). It shows while its title or message is set and until `until`.
+ * The whole alert can also be a bind to an object in the data.
+ */
+export interface AlertFields {
+    level?: 'info' | 'good' | 'warning' | 'danger' | Bind;
+    icon?: string | Bind;
+    title?: Value;
+    message?: Value;
+    /** Older name for `message`. */
+    text?: Value;
+    steps?: Value[] | Bind;
+    footer?: Value;
+    mode?: 'takeover' | 'banner';
+    /** ISO date and time after which the alert no longer shows. */
+    until?: Value;
+    /** Older name for `level`. */
+    state?: 'warning' | 'danger';
+}
+export type Alert = AlertFields | Bind;
+export interface ScreenDoc {
+    /** Format version, default 1. See src/version.ts. */
+    version?: number;
+    colors?: Colors;
+    alert?: Alert;
+    layout: Layout;
+    zones: Record<string, Component>;
+}
+export type Data = Record<string, unknown>;
+export {};

package/dist/types/validate-layout.d.ts

@@ -0,0 +1,2 @@
+/** Accepts either a fixed grid ("areas") or a flow ("flow"), not both. */
+export declare function layout(l: unknown, errs: string[]): string[];

package/dist/types/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ScreenDoc } from './types';
+export interface Result {
+    doc: ScreenDoc | null;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validate(input: unknown): Result;

package/dist/types/version.d.ts

@@ -0,0 +1,24 @@
+export declare const FORMAT = 1;
+type Obj = Record<string, unknown>;
+/** Upgrades a document from version N to N+1. */
+export type Migration = (doc: Obj) => {
+    doc: Obj;
+    notes: string[];
+};
+export type Migrations = Record<number, () => Promise<{
+    default: Migration;
+}>>;
+export interface Upgraded {
+    /** The document in the current format, or as written when newer. */
+    doc: unknown;
+    /** What changed or was lost on the way, as warnings. */
+    notes: string[];
+}
+/** The version a document declares, or null when it isn't a whole number. */
+export declare function versionOf(doc: Obj): number | null;
+/**
+ * Brings a parsed document to the current format. Documents already current,
+ * newer, or not even objects pass through untouched for validate() to judge.
+ */
+export declare function upgrade(input: unknown, migrations?: Migrations, current?: number): Promise<Upgraded>;
+export {};

package/dist/types/views.d.ts

@@ -0,0 +1,29 @@
+import type { JSX } from 'preact';
+import type { Data, ScreenDoc } from './types';
+export type AnyView = (p: {
+    c: never;
+    data: Data;
+}) => JSX.Element | null;
+declare const LOADERS: {
+    chart: () => Promise<AnyView | typeof import("./chart").Chart>;
+    meter: () => Promise<AnyView | typeof import("./measures").MeterView>;
+    meters: () => Promise<AnyView | typeof import("./measures").MetersView>;
+    bars: () => Promise<AnyView | typeof import("./measures").BarsView>;
+    split: () => Promise<AnyView | typeof import("./measures").SplitView>;
+    status: () => Promise<AnyView | typeof import("./lists").StatusView>;
+    schedule: () => Promise<AnyView | typeof import("./lists").ScheduleView>;
+    queue: () => Promise<AnyView | typeof import("./lists").QueueView>;
+    clocks: () => Promise<AnyView | typeof import("./lists").ClocksView>;
+    slideshow: () => Promise<AnyView | typeof import("./media").SlideshowView>;
+    qr: () => Promise<AnyView | typeof import("./media").QrView>;
+};
+export type LazyType = keyof typeof LOADERS;
+export declare const isLazy: (t: string) => t is LazyType;
+/** The view if its chunk is already here, so it renders without waiting. */
+export declare const loadedView: (t: LazyType) => AnyView | undefined;
+export declare function loadView(t: LazyType): Promise<AnyView>;
+/** Component types a document uses, stacks included. */
+export declare function usedTypes(doc: ScreenDoc): Set<string>;
+/** Loads every chunk the document needs, so the first paint is complete. */
+export declare function preloadViews(doc: ScreenDoc | null | undefined): Promise<void>;
+export {};

package/docs/api.md

@@ -0,0 +1,106 @@
+# API
+
+## Mounting a screen
+
+Give `mount()` an element and a document. The screen fills the element, so size the element the way you want the screen.
+
+```js
+import { mount } from '@514sid/signagekit'
+import '@514sid/signagekit/style.css'
+
+const screen = await mount(document.getElementById('screen'), {
+  layout: layoutYamlOrObject,
+  data: { menu: [['Tomato soup', '4.50']], wait: 6 },
+})
+
+// Later, when the values change:
+await screen.update({ data: { menu: [...], wait: 12 } })
+```
+
+Without a bundler, load it as a module with an import map. The YAML parser, uPlot and the QR encoder only download when a screen needs them.
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@514sid/signagekit@0.0.2/dist/style.css"
+/>
+<script type="importmap">
+  {
+    "imports": {
+      "@514sid/signagekit": "https://cdn.jsdelivr.net/npm/@514sid/signagekit@0.0.2/dist/index.js",
+      "preact": "https://cdn.jsdelivr.net/npm/preact@10.27.2/dist/preact.module.js",
+      "preact/hooks": "https://cdn.jsdelivr.net/npm/preact@10.27.2/hooks/dist/hooks.module.js",
+      "preact/jsx-runtime": "https://cdn.jsdelivr.net/npm/preact@10.27.2/jsx-runtime/dist/jsxRuntime.module.js",
+      "uplot": "https://cdn.jsdelivr.net/npm/uplot@1.6.32/dist/uPlot.esm.js",
+      "uqr": "https://cdn.jsdelivr.net/npm/uqr@0.1.3/dist/index.mjs",
+      "yaml": "https://cdn.jsdelivr.net/npm/yaml@2.9.1/browser/index.js"
+    }
+  }
+</script>
+<div id="screen" style="position: fixed; inset: 0"></div>
+<script type="module">
+  import { mount } from '@514sid/signagekit'
+  await mount(document.getElementById('screen'), { layout: '...', data: '...' })
+</script>
+```
+
+## `mount(element, options)`
+
+Renders a document into `element` and resolves with a handle once the screen is drawn, charts included. The canvas is 1080 px on the element's short side and follows its shape, then scales to fit with one CSS transform. When the element changes size, the layout reflows.
+
+| Option         | Default          | What it does                                                         |
+| -------------- | ---------------- | -------------------------------------------------------------------- |
+| `layout`       | required         | The document: JSON or YAML text, or an object.                       |
+| `data`         | `{}`             | Values that binds read: JSON or YAML text, or an object.             |
+| `scheme`       | `'dark'`         | `'dark'` or `'light'`, used when the document doesn't set one.       |
+| `accent`       | `'#2563eb'`      | Accent color, used when the document doesn't set one.                |
+| `colors`       | none             | Colors that win over the document's own, like `{ scheme: 'light' }`. |
+| `timeZone`     | device time zone | IANA time zone for clocks, dates and schedules.                      |
+| `locale`       | device locale    | BCP 47 locale for dates and times.                                   |
+| `showProblems` | `false`          | Shows errors and warnings over the screen. Useful while building.    |
+| `now`          | live clock       | A `Date` that freezes the clock, for screenshots and tests.          |
+
+`timeZone`, `locale` and `now` belong to the screen they are given to: several screens on one page can each use their own.
+
+The handle has:
+
+- `update({ layout?, data? })` replaces either or both and renders again.
+- `errors` and `warnings` hold the messages from the last check.
+- `report(message)` adds an error, which `showProblems` displays. Use it for your own failures, like a data request that didn't come back.
+- `destroy()` removes the screen and stops watching the element's size.
+
+`mount()` never throws on a bad document. Errors drop only what they affect: a broken layout renders nothing, a broken zone is left out, and warnings never block rendering.
+
+## `check(layout, data?, options?)`
+
+Parses and validates a document without rendering it. Resolves with `{ doc, data, errors, warnings }`. Run it on anything an assistant wrote before showing it. Options are `scheme`, `accent` and `colors`, which the contrast check uses, and `checkBinds: false`, which skips the warnings about binds that find nothing in the data, for data that arrives later.
+
+## `validate(object)`
+
+The synchronous core of `check()`, for an already parsed document. Returns `{ doc, errors, warnings }`. It doesn't upgrade older formats, since upgrades load on demand; use `check()` for documents that may be old.
+
+## `previewUrl(layout, data?, options?)`
+
+Resolves with a link to the [preview tool](preview.md) showing the screen. Options are the preview's parameters: `mode`, `size`, `scheme`, `accent`, `timeZone`, `locale`, `now` and `problems`, plus `base` for your own copy of the site. `pack()` and `unpack()` encode and decode the `#s=` part on their own.
+
+## Also exported
+
+`FORMAT` is the newest document format this version reads. `canvasSize(width, height)` returns the canvas size for a screen. `COLOR_KEYS`, `SCHEMES`, `ICON_NAMES` and `LEVELS` list the allowed colors, schemes, icons and alert levels. Every document type is exported too, from `ScreenDoc` down to each component.
+
+## Command line
+
+```bash
+npx @514sid/signagekit check screen.layout.yml screen.data.yml
+```
+
+Prints every error and warning with its exact path, low contrast and binds that find nothing in the data. It exits with 1 when there are errors, so it works as a gate in scripts and as a feedback loop for an assistant. `--scheme light` and `--accent '#hex'` match the contrast check to how you'll mount the screen.
+
+```bash
+npx @514sid/signagekit url screen.layout.yml screen.data.yml --mode sizes --now 2026-11-14T09:30
+```
+
+Prints a [preview](preview.md) link with the screen packed into it. It takes every preview parameter as a flag: `--mode`, `--size`, `--scheme`, `--accent`, `--tz`, `--locale`, `--now`, `--problems` and `--base`.
+
+## Browser support
+
+Browsers from 2020 on: current Chrome, Edge, Firefox and Safari, and the Chromium builds in signage players, smart TVs and sticks. It needs ES2020 and CSS grid. `ResizeObserver` is used when present.

package/docs/assistants.md

@@ -0,0 +1,55 @@
+# Writing screens with an AI assistant
+
+This guide is written to be handed to an assistant along with [format.md](format.md) and, for editors and validation, [schema.json](../schema.json). It covers what makes a screen read well from across a room and the mistakes assistants make most often.
+
+## How to work
+
+Write the layout once and put everything that changes in the data. A menu, a score, a list of arrivals or an alert lives in the data; the layout only says where it goes. After the first version, an update rewrites the data and leaves the layout alone, so a screen can't break because a value changed.
+
+Run `npx @514sid/signagekit check layout.yml data.yml` after every change and fix everything it prints, warnings included. A warning that a bind finds nothing in the data is almost always a typo in a path, and it shows as a dash on the screen. Then look at it. `npx @514sid/signagekit url layout.yml data.yml --mode sizes` prints a link to the [preview tool](preview.md); screenshot it once `html[data-status="ready"]` appears and check the screen at every resolution. Pass `--now` with a fixed time so clocks and schedules match between screenshots.
+
+## Layout
+
+- Start every document with `version: 1`, so it keeps working when the format changes.
+
+- Use a `flow` layout. Design it once for the orientation the screen mostly has (`design: landscape` or `portrait`), and it adapts to other shapes. Use `areas` only when a screen must look exactly as drawn.
+- Give headers and footers a fixed height in px, about 120 to 170 for a heading and 90 to 120 for a strip of messages. Let everything else share the remaining height with plain numbers.
+- Spans are out of 12 columns. Two or three zones per row reads well on a landscape screen; one or two on portrait.
+- Fewer, bigger zones read from further away. A screen seen from across a room works best with four to six zones and short lists. Each extra zone makes every text smaller.
+
+## Content
+
+- Don't set `size`. signagekit sizes all text together after every render, so tables, lists and stats on one screen share sizes. Pin a size only when the person asks for one.
+- Keep text short. Headings are a few words, cycle messages are one line each, and table cells are a word or a number. Long text doesn't shrink to fit: lists drop rows with "+N more" and tables page.
+- Use `stat` with `thresholds` instead of writing states into the data, so the data only carries numbers: `thresholds: { warning: 80, danger: 95 }`. With danger below warning, lower is worse.
+- Show state with `state`, never with color alone. States add an icon and a label as well as a color.
+- Give a bind a `fallback` when the value may be missing and a dash would confuse people: `{ bind: /wait, fallback: Ask at the desk }`.
+- Pick the component that matches the data: `bars` for a ranking, `meters` for values against limits, `split` for parts of one whole, `chart` for change over time, `status` for things that are up or down, `schedule` for a timetable, `queue` for "now serving".
+- Never ask for scrolling or moving text. `cycle` swaps whole messages instantly.
+
+## Alerts
+
+Bind the alert to the data, `alert: { bind: /alert }`, so raising one and clearing it are data changes:
+
+```yaml
+alert:
+  level: danger
+  icon: fire
+  title: Fire alarm
+  message: Leave the building now by the nearest exit.
+  steps: [Do not use the lifts, Gather at assembly point B]
+```
+
+Set it to `null` to bring the screen back. Pick the `icon` that names the situation from the list in [format.md](format.md#icons), keep the title to a few words, and put instructions in `steps`, one action each. Use `mode: banner` for notices that shouldn't hide the screen, and `until` for ones that should end on their own.
+
+## Colors
+
+Set `colors.scheme` so the screen looks the same everywhere, and set `accent` only when the person names a brand color. Fix every contrast warning: change the color the warning names, or remove it and let the scheme supply one.
+
+## YAML
+
+YAML data is read as text, so `4.50` stays `4.50`. In the layout, quote values that must stay text, like `delta: '+0.04'`. Quote any value that starts with `%`, `#`, `@` or `*`, and any value containing `: ` or, inside `{ }` and `[ ]`, a comma. When in doubt, write JSON.
+
+## A prompt to start from
+
+> You write screens for signagekit. A screen is a layout document and a data object, both YAML. Follow schema.json and docs/assistants.md. Put every value that can change in the data and bind to it. Use a flow layout with at most six zones. Don't set text sizes. After writing, run `npx @514sid/signagekit check` and fix every error and warning, then screenshot the link from `npx @514sid/signagekit url --mode sizes` and fix anything that looks cramped or empty before you answer. For later changes, edit only the data unless the person asks for a different layout.