@estiva-app/ui 0.74.1 → 0.75.0

package/dist/linked.d.ts

@@ -0,0 +1,168 @@
+/**
+ * What a link stands for, as the link widgets draw it (LinkChip, LinkRow,
+ * LinkCard, LinkPreview, CardUnder). The app builds it from its own lookup —
+ * every Estiva app from `@estiva-app/interop`'s projection — and hands it in
+ * whole: the words, the addresses, and the changes the reader may make. The
+ * widgets look nothing up, and keep nothing but what a reader does to them.
+ *
+ * The shape follows the prototype Miky approved (Widgets 2, 15 Oct; why:
+ * https://github.com/estiva-app/estiva-docs/blob/main/decisions/where-a-link-sits-and-which-file-gets-the-card.md).
+ */
+import type { ThingKind } from './KindIcon';
+/** What a link stands for, by its icon. `page` draws a page of text. */
+export type LinkedKind = ThingKind | 'page';
+/** The colours a status draws in, as an app's manifest names them. */
+export type StatusColour = 'neutral' | 'blue' | 'green' | 'muted';
+/** One value of a status, as the reader sees it. */
+export interface LinkedStatus {
+    label: string;
+    colour: StatusColour;
+}
+/** A person, by the name the app shows and, when it has one, their picture. */
+export interface LinkedPerson {
+    name: string;
+    picture?: string;
+}
+/** One choice a picker offers. */
+export interface PickerOption {
+    value: string;
+    label: string;
+    /** A status's colour: the option draws its shape. */
+    colour?: StatusColour;
+    /** A person's picture: the option draws their face. */
+    picture?: string;
+}
+/**
+ * A value the reader may be able to change from the card: a status, or who
+ * owns it. With `onChange` it is a picker; without it, the reader may not
+ * change it, and it reads as words in the same place.
+ */
+export interface LinkedPicker {
+    /** The chosen option's `value`; `undefined` is nobody, for an owner. */
+    value: string | undefined;
+    options: PickerOption[];
+    onChange?: (value: string) => void;
+}
+/** The count of what was said about it, and where that is read. */
+export interface LinkedConversation {
+    count: number;
+    /** Opens the conversation, at the first unread when there is one. */
+    href: string;
+    /**
+     * The reader has something unread there. Only a member of it has unread
+     * (SPEC §11.8; why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/membership-replaces-following.md),
+     * so the app passes `true` only for one.
+     */
+    unread?: boolean;
+}
+/** One item listed inside a card, such as a group's members, each opening on its own. */
+export interface LinkedChild {
+    id: string;
+    title: string;
+    href: string;
+    key?: string;
+    status: LinkedStatus;
+    owner?: LinkedPerson;
+}
+/** Everything a link's widgets may draw about what it stands for. Only `id`, `kind`, `title` and `href` are always there. */
+export interface Linked {
+    /** Its address. Two `Linked` with the same `id` are the same thing (identity by value, not by object). */
+    id: string;
+    kind: LinkedKind;
+    title: string;
+    /** Opens it. An address in this app goes through `AppProvider`'s `navigate`. */
+    href: string;
+    /** What the reader calls it, quietly before the title: "ABC-2". */
+    key?: string;
+    /** The line under a card's title: what it is in. Drawn after the key. */
+    subtitle?: string;
+    /** Its short summary, a sentence or two. Without one a card shows the title alone. */
+    summary?: string;
+    /** Its status: each option carries its `colour`. */
+    status?: LinkedPicker;
+    /** Who owns it, by the word the app uses (`ownerLabel`: "Assignee", "Lead"). */
+    owner?: LinkedPicker;
+    ownerLabel?: string;
+    /** What was said about it. `noun` names it for a screen reader: "comments" by default. */
+    conversation?: LinkedConversation & {
+        noun?: string;
+    };
+    /** Items inside it, drawn as rows in its card. */
+    children?: LinkedChild[];
+    /** How far along it is, drawn as a ring. */
+    done?: {
+        done: number;
+        total: number;
+    };
+    /** Who is in it, as faces. */
+    members?: LinkedPerson[];
+    /** Who wrote it, as faces. */
+    authors?: LinkedPerson[];
+    /** When it last changed, in the app's words: "2h ago". */
+    updated?: string;
+    /** The newest thing said in it, drawn only when the reader may read it. */
+    latest?: {
+        author: LinkedPerson;
+        body: string;
+        at: string;
+    };
+    /** Words a person wrote, linked as themselves: drawn with `author`'s face, not an icon. */
+    body?: string;
+    author?: LinkedPerson;
+}
+/** What a card's last line holds: pickers, faces, a line of words, or nothing. */
+export type LoadingFooter = 'pickers' | 'people' | 'line' | 'none';
+/** The parts of a card known before it loads, so its placeholder takes the card's height. */
+export interface LoadingShape {
+    subtitle?: boolean;
+    summary?: boolean;
+    rows?: number;
+    latest?: boolean;
+    ring?: boolean;
+    footer?: LoadingFooter;
+}
+/**
+ * Where a link's lookup stands. `loading` knows the kind from the address, and
+ * a shape when the app remembers one; `unavailable` is deleted or not the
+ * reader's to see, which read the same (Miky, 15 Oct).
+ */
+export type LinkState = {
+    state: 'loading';
+    kind: LinkedKind;
+    shape?: LoadingShape;
+} | {
+    state: 'unavailable';
+    kind: LinkedKind;
+    /** What it is, in a word: "Item". */
+    noun: string;
+    /** Where it may still open for someone who can: the app that owns it, and its address. */
+    openIn?: {
+        app: string;
+        href: string;
+    };
+} | {
+    state: 'ready';
+    linked: Linked;
+};
+/** A picker's chosen option, or none. */
+export declare function chosenOf(picker: LinkedPicker | undefined): PickerOption | undefined;
+/** The shape `linked`'s card takes, for its placeholder the next time it loads. */
+export declare function loadingShapeOf(linked: Linked): LoadingShape;
+/**
+ * What this device last found it could not show, kept so the next open draws
+ * "not available." from the first paint instead of a card's height that then
+ * closes (Peek's OPT-10; Miky, 15 Oct). One per app, under its own key, in
+ * localStorage because the first paint reads it synchronously. The app clears
+ * it with the rest of the device's copy at sign-out.
+ */
+export interface UnavailableMemory {
+    /** Whether this device last found `id` not available. */
+    has: (id: string) => boolean;
+    /** The lookup's answer: remembered when not available, forgotten when it is. */
+    note: (id: string, available: boolean) => void;
+    /** Sign-out. */
+    clear: () => void;
+}
+/** The device's memory of links it could not show, under the app's own `storageKey`, keeping the newest `limit`. */
+export declare function unavailableMemory(storageKey: string, limit?: number): UnavailableMemory;
+//# sourceMappingURL=linked.d.ts.map

package/dist/linked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked.d.ts","sourceRoot":"","sources":["../src/linked.ts"],"names":[],"mappings":"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"}

package/dist/linked.examples.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Placeholder links for the link widgets' stories and tests: neutral words,
+ * every field one of the widgets draws. Not exported from the package.
+ */
+import type { Linked, LinkState, PickerOption } from './linked';
+export declare const STATUS_OPTIONS: PickerOption[];
+export declare const PEOPLE: PickerOption[];
+/** A tracked item: a key, a status and an owner the reader may change, and a conversation. */
+export declare const ITEM: Linked;
+/** The same item, to a reader who may not change it. */
+export declare const ITEM_READ_ONLY: Linked;
+/** The same item with something unread in its conversation, as a member sees it. */
+export declare const ITEM_UNREAD: Linked;
+/** An item with no summary: its card shows the title alone. */
+export declare const ITEM_NO_SUMMARY: Linked;
+/** A group of items: its progress, its owner, and the items inside it. */
+export declare const GROUP: Linked;
+/** A place people talk: its members, when it last moved, and its newest conversation. */
+export declare const PLACE: Linked;
+/** A page of text: who wrote it, and when it last changed. */
+export declare const PAGE: Linked;
+/** Words a person wrote, linked as themselves. */
+export declare const SAID: Linked;
+export declare const ready: (linked: Linked) => LinkState;
+export declare const LOADING: LinkState;
+export declare const UNAVAILABLE: LinkState;
+//# sourceMappingURL=linked.examples.d.ts.map

package/dist/linked.examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked.examples.d.ts","sourceRoot":"","sources":["../src/linked.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,MAAM,EAAgB,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAI7E,eAAO,MAAM,cAAc,EAAE,YAAY,EAKxC,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,YAAY,EAIhC,CAAA;AAMD,8FAA8F;AAC9F,eAAO,MAAM,IAAI,EAAE,MAYlB,CAAA;AAED,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,MAAuG,CAAA;AAEpI,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,MAA0F,CAAA;AAEpH,+DAA+D;AAC/D,eAAO,MAAM,eAAe,EAAE,MAAiI,CAAA;AAE/J,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,MAgBnB,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,KAAK,EAAE,MAUnB,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,IAAI,EAAE,MASlB,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,IAAI,EAAE,MAQlB,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,SAAyC,CAAA;AAChF,eAAO,MAAM,OAAO,EAAE,SAA+C,CAAA;AACrE,eAAO,MAAM,WAAW,EAAE,SAAiH,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.74.1",
+  "version": "0.75.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",