@k2b/ui 0.44.0 → 0.46.0

package/dist/types/layout/DetailSections.d.ts

@@ -0,0 +1,156 @@
+import { type JSX } from "solid-js";
+import { type AvatarShape } from "../surfaces/Avatar";
+export type DetailPresencePerson = {
+    /** Stable key, such as the account id. */
+    id: string;
+    name: string;
+    /** A shorter name for the chip and the line below it, such as the first name. Defaults to `name`. */
+    shortName?: string;
+    src?: string | null;
+    icon?: string;
+    /** `square` for agents and service accounts. */
+    shape?: AvatarShape;
+    /** The person's color, the same as their cursor and comments. Defaults to `personColor(name)`. */
+    color?: string;
+    /** Writing shows a pen and the person's place; reading shows an eye. */
+    activity?: "writing" | "reading";
+    /** Where the person is, such as the heading of the section they write in. */
+    place?: string;
+    /** Short text at the end of the person's row in the full list, such as "2 tabs". */
+    trailing?: JSX.Element;
+    /** Goes to the person's place. */
+    onSelect?: () => void;
+    /** The person viewing: the fixed "You" chip at the end, never one of the others. */
+    self?: boolean;
+};
+/** `offline` keeps the last known people, pale and without live dots; `unavailable` offers `onRetry`. */
+export type DetailPresenceState = "live" | "loading" | "offline" | "unavailable";
+export type DetailPresenceProps = {
+    people: readonly DetailPresencePerson[];
+    state?: DetailPresenceState;
+    /**
+     * The quiet line below the people when it does not say who writes where: alone ("Whoever opens the note appears
+     * here"), offline ("Offline · as of 19:24"), or unavailable ("Your changes are still being saved").
+     */
+    note?: JSX.Element;
+    onRetry?: () => void;
+    /** One control at the end of the title row, such as "Copy link". */
+    actions?: JSX.Element;
+    /** Defaults to "Here now". */
+    title?: string;
+    /** One quiet line below the full list. */
+    listHint?: JSX.Element;
+    class?: string;
+};
+/**
+ * "Here now": who has the object open, what they do, and where. Always two lines tall in every state, so people
+ * coming, going, or moving never shift the panel. Chips that do not fit wrap into a hidden line and count as "+n";
+ * "+n" and "You" open the full list, which `AvatarStack` shows beside it or as a sheet on phones.
+ */
+export declare function DetailPresence(props: DetailPresenceProps): JSX.Element;
+/** A fixed slot at the end of a row for the people working there, such as an outline heading. Always the same width. */
+export declare function DetailPresenceSlot(props: {
+    people: readonly DetailPresencePerson[];
+    max?: number;
+}): JSX.Element;
+export type DetailAccessEntry = {
+    id: string;
+    name: string;
+    /** Sets the avatar: a person's picture or initials, a group, a service, all signed-in people, or public. */
+    kind?: "person" | "group" | "service" | "everyone" | "public";
+    src?: string | null;
+    /** One quiet word after the name, such as "Service". */
+    detail?: JSX.Element;
+    /** The role in words, such as "Can edit". */
+    role: JSX.Element;
+    /** The person viewing; listed as "You". */
+    self?: boolean;
+};
+export type DetailAccessProps = {
+    entries: readonly DetailAccessEntry[];
+    state?: "ready" | "loading" | "error";
+    onRetry?: () => void;
+    /** Rows before "Show n more". Defaults to 5. */
+    limit?: number;
+    /** A way to change access, only for people who may; others read the list. */
+    manage?: {
+        label: string;
+        href?: string;
+        onClick?: () => void;
+    };
+    /** A quiet line below the list, such as "Applies to the whole notebook". */
+    note?: JSX.Element;
+    /** Defaults to "Access". */
+    title?: string;
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    class?: string;
+};
+/**
+ * Who has access and with which role, read-only. Closed it names the first entries; open it lists `limit` rows and
+ * "Show n more". A list that may load later passes `state="loading"` and keeps its place.
+ */
+export declare function DetailAccess(props: DetailAccessProps): JSX.Element;
+export type DetailLinkItem = {
+    id: string;
+    title: string;
+    href?: string;
+    onClick?: (event: MouseEvent) => void;
+    /** Defaults to a document. */
+    icon?: string;
+    /** Quiet text at the end, such as the other notebook's name. */
+    trailing?: JSX.Element;
+};
+export type DetailLinksProps = {
+    /** What links here. */
+    incoming: readonly DetailLinkItem[];
+    /** What this object links to. */
+    outgoing: readonly DetailLinkItem[];
+    /** Rows per direction before "Show n more". Defaults to 5. */
+    limit?: number;
+    /** Defaults to "Links". */
+    title?: string;
+    defaultOpen?: boolean;
+    class?: string;
+};
+/** "Linked from" and "Links to" in one section. Without links it is one row: the title and "None yet". */
+export declare function DetailLinks(props: DetailLinksProps): JSX.Element;
+export type DetailProperty = {
+    id: string;
+    label: JSX.Element;
+    value: JSX.Element;
+    /** An avatar or icon before the value. */
+    leading?: JSX.Element;
+    /** Makes the value a link, such as "23 versions" to the version history. */
+    href?: string;
+};
+export type DetailPropertiesProps = {
+    items: readonly DetailProperty[];
+    /** Defaults to "Properties". */
+    title?: string;
+    icon?: string;
+    /** One line for the closed section, such as "412 words · created 12 March by Jana Berger". */
+    summary?: JSX.Element;
+    /** Open by default only when the properties are the object's main content. */
+    defaultOpen?: boolean;
+    class?: string;
+};
+/** Facts about the object as label and value rows, such as created, edited, size, and the way to its history. */
+export declare function DetailProperties(props: DetailPropertiesProps): JSX.Element;
+export type DetailTag = {
+    id: string;
+    label: string;
+    /** Where the tag leads, such as everything with that tag. */
+    href?: string;
+};
+export type DetailTagsProps = {
+    tags: readonly DetailTag[];
+    /** Defaults to "Tags". */
+    title?: string;
+    /** Shown without tags, such as how to add one. */
+    emptyHint?: JSX.Element;
+    class?: string;
+};
+/** The object's tags as chips; a chip with `href` leads to everything with that tag. */
+export declare function DetailTags(props: DetailTagsProps): JSX.Element;

package/dist/types/layout/DetailsToggle.d.ts

@@ -0,0 +1,13 @@
+import { type JSX } from "solid-js";
+import { type IconButtonProps } from "../actions/Button";
+/** The one icon for "Details" in every app: a circle, so it never reads as the side panel's rectangle with an arrow. */
+export declare const DETAILS_ICON = "ti ti-info-circle";
+export type DetailsToggleProps = Omit<IconButtonProps, "children" | "variant"> & {
+    /** Extra classes for the glyph, such as a text size in a dense toolbar. */
+    iconClass?: string;
+};
+/**
+ * An icon-only Details button for an app's own toolbar or reader head. It shows the selection fill while its panel
+ * is open (`aria-expanded="true"`), without a border or shadow, like `AppWorkspace.Detail`'s own button.
+ */
+export declare function DetailsToggle(props: DetailsToggleProps): JSX.Element;

package/dist/types/layout/PageTitle.d.ts

@@ -38,9 +38,16 @@ export declare const setPageTrail: (trail: PageTrailState) => void;
  * the context carries it; the provider also publishes it into the document,
  * where browser-rendered parts such as islands read it. Below a provider that
  * renders in the browser, its `trail` prop is the source: update the prop.
+ *
+ * `onOwnTitle` runs on the server for each `PageTitle` below that is not a
+ * fallback. The host then sets `data-k2b-own-title` on an element around the
+ * page, inside the `k2b-ui` root, so the chrome's fallback titles step back.
+ * With `data-k2b-title-host` on that element, titles that mount or leave in
+ * the browser keep the attribute current.
  */
 export declare function PageTrailProvider(props: {
     trail: PageTrailState | undefined;
+    onOwnTitle?: () => void;
     children: JSX.Element;
 }): JSX.Element;
 /** The host's page trail: from the provider while rendering below it, otherwise from the document. */

package/dist/types/layout/PanelDialog.d.ts

@@ -1,8 +1,11 @@
 import { type JSX } from "solid-js";
+import { type DialogTone } from "../feedback/dialog-tone";
 export type PanelDialogSurface = "contained" | "floating";
 export type PanelDialogProps = {
     children: JSX.Element;
     surface?: PanelDialogSurface;
+    /** A 2 px edge in the tone's colour inside the dialog frame; the header shows the tone's icon instead of its own. */
+    tone?: DialogTone;
 };
 export type PanelDialogHeaderProps = {
     title: JSX.Element;

package/dist/types/layout/Settings.d.ts

@@ -25,7 +25,8 @@ export type SettingsSectionProps = {
 };
 /**
  * A full-page settings group: a heading, optional actions and its fields on the
- * page surface without a card. Dialogs keep using PanelDialog.Section.
+ * page surface without a card. From 860 px of its own width the heading takes a
+ * column beside the fields. Dialogs keep using PanelDialog.Section.
  */
 export declare function SettingsSection(props: SettingsSectionProps): JSX.Element;
 export type SettingsGroupProps = {
@@ -46,11 +47,26 @@ export declare const readSettingsError: (response: Pick<Response, "json">, fallb
     message: string;
     fields: Record<string, string>;
 }>;
+/**
+ * The room a setting's control takes: `short` for a number, `medium` for a choice, `long` for text, and `full` for
+ * an editor, which keeps its name above it and takes the whole row.
+ */
+export type SettingsFieldWidth = "short" | "medium" | "long" | "full";
 export type SettingsFieldProps = {
     label: string;
+    /** One sentence of help; longer guidance belongs in the page's guide. */
     description: string;
     error: MaybeAccessor<string | undefined>;
     changed?: MaybeAccessor<boolean>;
+    /**
+     * Where the value comes from, at a fixed place after the control: quiet text such as "Default", or the one way
+     * back to it, such as a Reset button that only a value of its own shows.
+     */
+    source?: JSX.Element;
+    /** The control's width by kind, so a number never stretches like a URL. Defaults to `long`, the full column. */
+    width?: SettingsFieldWidth;
+    /** The row's id, for a link that leads to this one setting. */
+    id?: string;
     children: JSX.Element | ((control: SettingsFieldControlProps) => JSX.Element);
     class?: string;
 };

package/dist/types/layout/detail-sections-messages.d.ts

@@ -0,0 +1,59 @@
+/** Titles and sentences of the shared detail sections: presence, access, links, properties, and tags. */
+declare const detailSectionMessages: import("@k2b/stdlib").Catalog<{
+    hereNow: string;
+    onlyYou: string;
+    you: string;
+    writesIn: string;
+    writing: string;
+    reading: string;
+    readingAlong: ({ names, count }: {
+        names: string;
+        count: number;
+    }) => string;
+    and: string;
+    jumpTo: ({ name, place }: {
+        name: string;
+        place: string;
+    }) => string;
+    personWriting: ({ name, place }: {
+        name: string;
+        place: string;
+    }) => string;
+    personReading: ({ name }: {
+        name: string;
+    }) => string;
+    everyoneHere: ({ count }: {
+        count: number;
+    }) => string;
+    presenceLoading: string;
+    presenceUnavailable: string;
+    retry: string;
+    access: string;
+    accessLoading: string;
+    accessFailed: string;
+    accessSummary: ({ names, more }: {
+        names: string;
+        more: number;
+    }) => string;
+    links: string;
+    linkedBy: ({ count }: {
+        count: number;
+    }) => string;
+    linksTo: ({ count }: {
+        count: number;
+    }) => string;
+    linkedBySummary: ({ names, more }: {
+        names: string;
+        more: number;
+    }) => string;
+    linksToSummary: ({ names, more }: {
+        names: string;
+        more: number;
+    }) => string;
+    properties: string;
+    tags: string;
+}>;
+export type DetailSectionMessages = ReturnType<(typeof detailSectionMessages)["resolve"]>["t"];
+export declare const useDetailSectionMessages: () => (() => DetailSectionMessages);
+export declare const checkDetailSectionMessages: () => import("@k2b/stdlib").CatalogIssue[];
+export {};

package/dist/types/layout/index.d.ts

@@ -11,8 +11,11 @@ export { APP_WORKSPACE_DETAIL_DEFAULT, APP_WORKSPACE_DETAIL_MAX, APP_WORKSPACE_D
 export { type BottomSheetProps, bottomSheetAdaptiveOptions, bottomSheetOptions, default as BottomSheet } from "./BottomSheet";
 export type { DataPanelProps } from "./DataPanel";
 export { DataPanel } from "./DataPanel";
-export type { DetailPanelActionButtonProps, DetailPanelActionLinkProps, DetailPanelActionProps, DetailPanelActionSecondary, DetailPanelBodyProps, DetailPanelGroupProps, DetailPanelHeaderProps, DetailPanelProps, DetailPanelSectionProps, DetailPanelSummaryProps, DetailPanelTone, } from "./DetailPanel";
+export type { DetailPanelActionButtonProps, DetailPanelActionLinkProps, DetailPanelActionProps, DetailPanelActionSecondary, DetailPanelBodyProps, DetailPanelGroupProps, DetailPanelHeaderProps, DetailPanelProps, DetailPanelRowProps, DetailPanelSectionProps, DetailPanelSummaryProps, DetailPanelTone, } from "./DetailPanel";
 export { default as DetailPanel } from "./DetailPanel";
+export type { DetailAccessEntry, DetailAccessProps, DetailLinkItem, DetailLinksProps, DetailPresencePerson, DetailPresenceProps, DetailPresenceState, DetailPropertiesProps, DetailProperty, DetailTag, DetailTagsProps, } from "./DetailSections";
+export { DetailAccess, DetailLinks, DetailPresence, DetailPresenceSlot, DetailProperties, DetailTags } from "./DetailSections";
+export { DETAILS_ICON, DetailsToggle, type DetailsToggleProps } from "./DetailsToggle";
 export type { DiscussionComposerProps, DiscussionItemProps, DiscussionListProps, DiscussionProps } from "./Discussion";
 export { default as Discussion } from "./Discussion";
 export type { FloatingWindowClose, FloatingWindowProps, OpenFloatingWindowOptions, } from "./FloatingWindow";
@@ -38,7 +41,7 @@ export { default as ResizeSeparator, type ResizeSeparatorProps } from "./ResizeS
 export { attachResizeSeparator, type ResizeSeparatorOptions } from "./resize-separator";
 export type { ScrollAreaProps } from "./ScrollArea";
 export { default as ScrollArea } from "./ScrollArea";
-export type { SaveStatusProps, SaveStatusState, SettingsFieldControlProps, SettingsFieldProps, SettingsGroupActionProps, SettingsGroupProps, SettingsPageProps, SettingsPanelFooterProps, SettingsSaveBarProps, SettingsSectionProps, } from "./Settings";
+export type { SaveStatusProps, SaveStatusState, SettingsFieldControlProps, SettingsFieldProps, SettingsFieldWidth, SettingsGroupActionProps, SettingsGroupProps, SettingsPageProps, SettingsPanelFooterProps, SettingsSaveBarProps, SettingsSectionProps, } from "./Settings";
 export { readSettingsError, SaveStatus, SettingsField, SettingsGroup, SettingsPage, SettingsPanelFooter, SettingsSaveBar, SettingsSection, sameSettingValue, } from "./Settings";
 export type { SettingsCollectionActionProps, SettingsCollectionItemActionsProps, SettingsCollectionItemProps, SettingsCollectionItemReorderProps, SettingsCollectionItemStatusProps, SettingsCollectionProps, } from "./SettingsCollection";
 export { default as SettingsCollection } from "./SettingsCollection";

package/dist/types/surfaces/Avatar.d.ts

@@ -9,6 +9,8 @@ export type AvatarRing = "success" | {
 };
 /** `square` marks an agent or service account; people stay round. */
 export type AvatarShape = "circle" | "square";
+/** `person` tints initials and icons by name; `neutral` keeps them gray, such as for someone outside the team. */
+export type AvatarTone = "person" | "neutral";
 export type AvatarProps = {
     name: string;
     src?: string | null;
@@ -19,6 +21,7 @@ export type AvatarProps = {
     /** Draws a ring with a small transparent gap inside the avatar's own box, so the avatar keeps its size and no container clips the ring. */
     ring?: AvatarRing;
     shape?: AvatarShape;
+    tone?: AvatarTone;
     loading?: "eager" | "lazy";
     class?: string;
     style?: JSX.CSSProperties | string;

package/dist/types/surfaces/AvatarStack.d.ts

@@ -1,5 +1,5 @@
 import { type JSX } from "solid-js";
-import { type AvatarShape } from "./Avatar";
+import { type AvatarShape, type AvatarTone } from "./Avatar";
 export type AvatarStackPerson = {
     /** Stable key, such as the account id. */
     id: string;
@@ -32,8 +32,27 @@ export type AvatarStackProps = {
     hint?: JSX.Element;
     /** Faces before "+n". Defaults to 3. */
     max?: number;
+    /** What the button shows instead of the faces, such as a "+n" chip and the viewer's own chip. */
+    trigger?: JSX.Element;
     class?: string;
 };
+export type AvatarFacesPerson = Pick<AvatarStackPerson, "name" | "src" | "icon" | "shape"> & {
+    tone?: AvatarTone;
+};
+export type AvatarFacesProps = {
+    people: readonly AvatarFacesPerson[];
+    /** Faces before "+n". Defaults to 3. */
+    max?: number;
+    /** Everyone the faces stand for when `people` lists only some of them; "+n" counts the rest. */
+    total?: number;
+    /** `sm` (default) matches the stack button; `md` suits a row or table cell whose text the faces stand beside. */
+    size?: "sm" | "md";
+};
+/**
+ * The stack's faces and "+n" without its button or list, for a row or link that is already interactive. The faces
+ * are decorative: name the people in the surrounding label or a tooltip.
+ */
+export declare function AvatarFaces(props: AvatarFacesProps): JSX.Element;
 /**
  * A few overlapping faces, then "+n", as one button. It opens the full list of people beside it, or as a bottom sheet
  * on phones. People with `self` are listed last and never shown in the stack.

package/dist/types/surfaces/ChangeList.d.ts

@@ -0,0 +1,20 @@
+import { type JSX } from "solid-js";
+/** `add` gains something, `change` alters it, `remove` takes it away, `neutral` names a setting. */
+export type ChangeTone = "add" | "change" | "remove" | "neutral" | "warning";
+export type ChangeListItem = {
+    tone: ChangeTone;
+    /** A Tabler icon class; defaults to plus, arrows or minus by tone. */
+    icon?: string;
+    content: JSX.Element;
+    /** One quiet line under the content, such as what the change means for others. */
+    detail?: JSX.Element;
+};
+export type ChangeListProps = {
+    items: readonly ChangeListItem[];
+    /** Names the list for assistive technology, such as "What changes". */
+    label: string;
+    class?: string;
+};
+/** Pending changes before they are saved, one line each, so a person can check them in one look. */
+export declare function ChangeList(props: ChangeListProps): JSX.Element;
+export default ChangeList;

package/dist/types/surfaces/StatusBadge.d.ts

@@ -5,6 +5,11 @@ export type StatusBadgeProps = {
     label: JSX.Element;
     icon?: string | null;
     variant?: "chip" | "dot" | "text";
+    /**
+     * Every label this place can show, such as all states of a list's status. The badge keeps the width of the longest,
+     * so in a right-aligned slot its dot starts at one x in every row and stays put when the state changes.
+     */
+    labels?: readonly string[];
     title?: string;
     class?: string;
 };

package/dist/types/surfaces/index.d.ts

@@ -1,7 +1,9 @@
-export type { AvatarProps, AvatarRing, AvatarShape, AvatarSize } from "./Avatar";
+export type { AvatarProps, AvatarRing, AvatarShape, AvatarSize, AvatarTone } from "./Avatar";
 export { Avatar } from "./Avatar";
-export type { AvatarStackPerson, AvatarStackProps } from "./AvatarStack";
-export { AvatarStack } from "./AvatarStack";
+export type { AvatarFacesPerson, AvatarFacesProps, AvatarStackPerson, AvatarStackProps } from "./AvatarStack";
+export { AvatarFaces, AvatarStack } from "./AvatarStack";
+export type { ChangeListItem, ChangeListProps, ChangeTone } from "./ChangeList";
+export { ChangeList } from "./ChangeList";
 export type { DescriptionListItem, DescriptionListProps } from "./DescriptionList";
 export { DescriptionList } from "./DescriptionList";
 export type { DotStripProps, DotStripTone } from "./DotStrip";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -91,13 +91,13 @@
     "qr-scanner": "1.4.2"
   },
   "peerDependencies": {
-    "@k2b/ssr": "^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0 || ^0.18.0 || ^0.19.0 || ^0.20.0",
+    "@k2b/ssr": "^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0 || ^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0",
     "solid-js": "^1.9.10"
   },
   "devDependencies": {
     "@babel/core": "8.0.6",
     "@babel/preset-typescript": "8.0.1",
-    "@k2b/ssr": "0.20.2",
+    "@k2b/ssr": "0.21.0",
     "@types/babel__core": "7.20.5",
     "@types/bun": "1.4.2",
     "axe-core": "4.11.0",