@cratis/scene.blueprint.default 4.39.0 → 4.40.0

package/foundation/urlState.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useEffect, useState } from 'react';
+
+/** Reads one query-string parameter of the current address, or undefined when it is absent or there is no address (server rendering). */
+export function readUrlParameter(name: string): string | undefined {
+    if (typeof window === 'undefined') return undefined;
+    const value = new URLSearchParams(window.location.search).get(name);
+    return value === null ? undefined : value;
+}
+
+/** Writes one query-string parameter to the address without adding a history entry; an undefined or empty value removes it. */
+export function writeUrlParameter(name: string, value: string | undefined): void {
+    if (typeof window === 'undefined') return;
+    const parameters = new URLSearchParams(window.location.search);
+    if (value === undefined || value === '') parameters.delete(name);
+    else parameters.set(name, value);
+
+    const query = parameters.toString();
+    window.history.replaceState(window.history.state, '', `${window.location.pathname}${query.length > 0 ? `?${query}` : ''}${window.location.hash}`);
+}
+
+/**
+ * State that lives in the address bar: a list's search, sort, page and filters, a master/detail's selection, a module's active section.
+ *
+ * It starts from the address when the address has a value (so a shared link, a refresh and the back button restore the screen as it was),
+ * otherwise from the fallback the template supplies. Changing it rewrites the address in place and does not add a history entry per keystroke.
+ * Several components on one screen use distinct `key`s; a template names them (`q`, `sort`, `page`, `selected`, `section`). Without a
+ * `urlKey` the state is plain component state, which is what a gallery card and a design surface want.
+ *
+ * @param key The query-string parameter, or undefined to keep the state local.
+ * @param fallback The value used when the address has none.
+ * @returns The value and its setter.
+ */
+export function useUrlState(key: string | undefined, fallback: string | undefined): [string | undefined, (value: string | undefined) => void] {
+    const [value, setValue] = useState<string | undefined>(() => (key === undefined ? fallback : readUrlParameter(key) ?? fallback));
+
+    useEffect(() => {
+        if (key === undefined) return;
+        const restore = () => setValue(readUrlParameter(key) ?? fallback);
+        window.addEventListener('popstate', restore);
+        return () => window.removeEventListener('popstate', restore);
+    }, [key, fallback]);
+
+    const update = useCallback((next: string | undefined) => {
+        setValue(next);
+        if (key !== undefined) writeUrlParameter(key, next);
+    }, [key]);
+
+    return [value, update];
+}

package/foundation/useCompactWidth.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useState } from 'react';
+
+/** The width below which a screen is a phone's: the collapse rules of Part B 1.3 (list to cards, master-detail to stack) apply under it. */
+export const compactQuery = '(max-width: 40rem)';
+
+/** Whether the viewport is phone-wide, kept up to date. Without `matchMedia` (a test environment, server rendering) it is false, so the full layout renders. */
+export function useCompactWidth(): boolean {
+    const [compact, setCompact] = useState(() => typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia(compactQuery).matches);
+
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+        const query = window.matchMedia(compactQuery);
+        const update = () => setCompact(query.matches);
+        update();
+        query.addEventListener('change', update);
+        return () => query.removeEventListener('change', update);
+    }, []);
+
+    return compact;
+}

package/foundation/wizardModel.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** One step of a wizard. */
+export interface WizardStep {
+    id: string;
+    label: string;
+    /** Whether the step's own fields are valid; a step that is not valid blocks Next. Defaults to true. */
+    valid: boolean;
+}
+
+/** Where a step stands for the person going through the wizard. */
+export enum StepStatus {
+    Completed = 'completed',
+    Current = 'current',
+    Upcoming = 'upcoming',
+}
+
+/** Reads steps, dropping those without an id and repeated ids. */
+export function readWizardSteps(value: unknown): WizardStep[] {
+    if (!Array.isArray(value)) return [];
+
+    const seen = new Set<string>();
+    return value.flatMap((entry): WizardStep[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { id, label, valid } = entry as Record<string, unknown>;
+        if (typeof id !== 'string' || id.length === 0 || seen.has(id)) return [];
+        seen.add(id);
+        return [{ id, label: typeof label === 'string' && label.length > 0 ? label : id, valid: valid !== false }];
+    });
+}
+
+/** The step to show: the requested one when it exists and every step before it is completed, else the furthest step that is reachable. A refresh can never land past a step that was not done. */
+export function reachableStep(steps: WizardStep[], completed: ReadonlySet<string>, requested: string | undefined): string | undefined {
+    const wanted = steps.findIndex(step => step.id === requested);
+    let furthest = 0;
+    while (furthest < steps.length - 1 && completed.has(steps[furthest].id)) furthest++;
+    return steps[wanted >= 0 && wanted <= furthest ? wanted : furthest]?.id;
+}
+
+/** The status of a step: the current one, a completed one (revisitable), or upcoming. */
+export function statusOf(completed: ReadonlySet<string>, current: string | undefined, id: string): StepStatus {
+    if (id === current) return StepStatus.Current;
+    return completed.has(id) ? StepStatus.Completed : StepStatus.Upcoming;
+}
+
+/** Whether a step may be opened from the progress indicator: a completed one, the current one, or the next one when the current is done. */
+export function canOpen(steps: WizardStep[], completed: ReadonlySet<string>, id: string): boolean {
+    const index = steps.findIndex(step => step.id === id);
+    return index === 0 || steps.slice(0, index).every(step => completed.has(step.id));
+}
+
+/** The step before or after another, or undefined at either end. */
+export const neighbour = (steps: WizardStep[], id: string | undefined, direction: -1 | 1): WizardStep | undefined => steps[steps.findIndex(step => step.id === id) + direction];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.blueprint.default",
-    "version": "4.39.0",
+    "version": "4.40.0",
     "description": "The default blueprint: application shell layouts, the screen and dialog templates that go inside them, the components that fill their slots, and two themes.",
     "keywords": [
         "cratis",
@@ -55,15 +55,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.39.0",
-        "@cratis/scene.model": "4.39.0",
-        "@cratis/scene.react": "4.39.0"
+        "@cratis/scene.engine": "4.40.0",
+        "@cratis/scene.model": "4.40.0",
+        "@cratis/scene.react": "4.40.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.39.0",
-        "@cratis/scene.model": "4.39.0",
-        "@cratis/scene.primereact": "4.39.0",
-        "@cratis/scene.react": "4.39.0",
+        "@cratis/scene.engine": "4.40.0",
+        "@cratis/scene.model": "4.40.0",
+        "@cratis/scene.primereact": "4.40.0",
+        "@cratis/scene.react": "4.40.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primeuix/themes": "^3.0.1",

package/shell/layout.css

@@ -1120,6 +1120,12 @@
     --foundation-row-height: 2.75rem;
 
     box-sizing: border-box;
+    /*
+     * A component is often a grid or flex item of the slot it sits in, whose minimum size is its content's. Without this a wide table or board
+     * stretches its cell, and the page, instead of scrolling inside itself.
+     */
+    min-inline-size: 0;
+    max-inline-size: 100%;
     color: var(--foundation-text);
     font-family: inherit;
 }
@@ -1979,6 +1985,7 @@
 }
 
 .foundation-matrix-scroll {
+    position: relative; /* the containing block of the visually hidden text inside, so it scrolls with the content instead of widening the page */
     overflow-x: auto;
 }
 
@@ -2025,3 +2032,509 @@
     align-items: center;
     justify-content: center;
 }
+
+/* Tabs, sub-navigation, bulk bar, search and notifications. */
+.foundation-tabs {
+    position: relative; /* the containing block of the visually hidden text inside, so it scrolls with the content instead of widening the page */
+    display: flex;
+    gap: var(--foundation-space-1);
+    overflow-x: auto;
+    border-block-end: 1px solid var(--foundation-border);
+}
+
+.foundation-tab {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    min-block-size: 2.75rem;
+    padding-inline: var(--foundation-space-3);
+    border: 0;
+    border-block-end: 3px solid transparent;
+    background: transparent;
+    color: var(--foundation-muted);
+    font: inherit;
+    font-weight: 600;
+    white-space: nowrap;
+    cursor: pointer;
+}
+
+.foundation-tab[aria-selected='true'] {
+    border-block-end-color: var(--foundation-primary);
+    color: var(--foundation-text);
+}
+
+.foundation-tab:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.foundation-tab-badge {
+    padding: 0 var(--foundation-space-2);
+    border-radius: 999px;
+    background: var(--foundation-hover);
+    color: var(--foundation-text);
+    font-size: 0.75rem;
+}
+
+.foundation-tab-panel {
+    padding-block: var(--foundation-space-3);
+}
+
+.foundation-tab-panel[hidden] {
+    display: none;
+}
+
+.foundation-subnav ul {
+    display: flex;
+    gap: var(--foundation-space-1);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-subnav[data-orientation='vertical'] ul {
+    flex-direction: column;
+}
+
+.foundation-subnav-link {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--foundation-space-2);
+    min-block-size: 2.5rem;
+    padding-inline: var(--foundation-space-3);
+    border-radius: var(--foundation-radius);
+    color: var(--foundation-text);
+    font-weight: 600;
+    text-decoration: none;
+}
+
+.foundation-subnav-link:hover {
+    background: var(--foundation-hover);
+}
+
+.foundation-subnav-link[aria-current='page'] {
+    background: var(--foundation-highlight);
+    color: var(--foundation-highlight-text);
+}
+
+.foundation-bulk-bar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--foundation-space-3);
+    padding: var(--foundation-space-2) var(--foundation-space-4);
+    border: 1px solid var(--foundation-primary);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-highlight);
+    color: var(--foundation-highlight-text);
+}
+
+.foundation-bulk-bar[hidden] {
+    display: none;
+}
+
+.foundation-bulk-actions {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: var(--foundation-space-2);
+}
+
+.foundation-search {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    padding-inline: var(--foundation-space-3);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-search input[type='search'] {
+    min-inline-size: 12rem;
+    border: 0;
+    background: transparent;
+}
+
+.foundation-notifications {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: 2.5rem;
+    min-block-size: 2.5rem;
+    border: 0;
+    border-radius: var(--foundation-radius);
+    background: transparent;
+    color: var(--foundation-text);
+    font-size: 1.25rem;
+    cursor: pointer;
+}
+
+.foundation-notifications:hover {
+    background: var(--foundation-hover);
+}
+
+.foundation-notifications-badge {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-end: 0;
+    min-inline-size: 1.25rem;
+    padding-inline: var(--foundation-space-1);
+    border-radius: 999px;
+    background: var(--foundation-danger);
+    color: var(--foundation-surface);
+    font-size: 0.75rem;
+    font-weight: 700;
+    line-height: 1.25rem;
+    text-align: center;
+}
+
+/* Data list: table, cards, groups, pager. */
+.foundation-data-list {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-3);
+}
+
+.foundation-table-scroll {
+    position: relative; /* the containing block of the visually hidden text inside, so it scrolls with the content instead of widening the page */
+    overflow-x: auto;
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-table {
+    inline-size: 100%;
+    border-collapse: collapse;
+}
+
+.foundation-table th,
+.foundation-table td {
+    min-block-size: var(--foundation-row-height);
+    padding: var(--foundation-space-2) var(--foundation-space-3);
+    border-block-end: 1px solid var(--foundation-border);
+    text-align: start;
+    white-space: nowrap;
+}
+
+.foundation-table thead th {
+    background: var(--foundation-background);
+    color: var(--foundation-muted);
+    font-size: 0.875rem;
+}
+
+.foundation-table td[data-kind='number'],
+.foundation-table td[data-kind='currency'] {
+    font-variant-numeric: tabular-nums;
+    text-align: end;
+}
+
+.foundation-table tr[data-selected='true'] {
+    background: var(--foundation-highlight);
+}
+
+.foundation-table-select {
+    inline-size: 2.5rem;
+}
+
+.foundation-sort {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--foundation-space-1);
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.foundation-row-actions {
+    max-inline-size: 8rem;
+}
+
+.foundation-cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
+    gap: var(--foundation-space-3);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-card-row {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-2);
+    padding: var(--foundation-space-3);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-card-row[data-selected='true'] {
+    border-color: var(--foundation-primary);
+}
+
+.foundation-card-head {
+    display: flex;
+    align-items: center;
+    gap: var(--foundation-space-2);
+}
+
+.foundation-card-row dl {
+    display: grid;
+    gap: var(--foundation-space-1);
+    margin: 0;
+}
+
+.foundation-card-row dd {
+    margin: 0;
+}
+
+.foundation-list-group h3 {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin: 0 0 var(--foundation-space-2);
+    font-size: 1rem;
+}
+
+.foundation-pager {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--foundation-space-3);
+}
+
+/* Kanban board. */
+.foundation-board {
+    position: relative; /* the containing block of the visually hidden text inside, so it scrolls with the content instead of widening the page */
+    display: flex;
+    gap: var(--foundation-space-3);
+    overflow-x: auto;
+    padding-block-end: var(--foundation-space-2);
+}
+
+.foundation-board-column {
+    display: flex;
+    flex: 1 0 15rem;
+    flex-direction: column;
+    gap: var(--foundation-space-2);
+    max-inline-size: 22rem;
+    padding: var(--foundation-space-2);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-background);
+}
+
+.foundation-board-column[data-collapsed='true'] {
+    flex-basis: auto;
+}
+
+.foundation-board-column[data-over='true'] {
+    border-color: var(--foundation-danger);
+}
+
+.foundation-board-header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--foundation-space-2);
+}
+
+.foundation-board-header h3 {
+    margin: 0;
+    font-size: 1rem;
+}
+
+.foundation-board-cards {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-2);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-board-card {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-1);
+    padding: var(--foundation-space-3);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-board-card[draggable='true'] {
+    cursor: grab;
+}
+
+.foundation-board-badges {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: var(--foundation-space-1);
+}
+
+/* Wizard. */
+.foundation-wizard-steps {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--foundation-space-3);
+    margin: 0 0 var(--foundation-space-4);
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-wizard-step button {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    min-block-size: 2.5rem;
+    padding: 0 var(--foundation-space-2);
+    border: 0;
+    border-radius: var(--foundation-radius);
+    background: transparent;
+    color: var(--foundation-muted);
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.foundation-wizard-step button:disabled {
+    cursor: not-allowed;
+    opacity: 0.6;
+}
+
+.foundation-wizard-step[data-status='current'] button {
+    color: var(--foundation-text);
+}
+
+.foundation-wizard-marker {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1.75rem;
+    block-size: 1.75rem;
+    border: 2px solid currentColor;
+    border-radius: 50%;
+    font-size: 0.875rem;
+}
+
+.foundation-wizard-step[data-status='current'] .foundation-wizard-marker {
+    background: var(--foundation-primary);
+    border-color: var(--foundation-primary);
+    color: var(--foundation-primary-contrast);
+}
+
+.foundation-wizard-step[data-status='completed'] .foundation-wizard-marker {
+    border-color: var(--foundation-success);
+    color: var(--foundation-success);
+}
+
+.foundation-wizard-body {
+    padding-block: var(--foundation-space-3);
+}
+
+.foundation-wizard-actions,
+.foundation-form-actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    padding-block: var(--foundation-space-3);
+    border-block-start: 1px solid var(--foundation-border);
+}
+
+.foundation-wizard-spacer {
+    flex: 1;
+}
+
+/* Form. */
+.foundation-form-section {
+    margin: 0 0 var(--foundation-space-4);
+    padding: var(--foundation-space-3) var(--foundation-space-4);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+}
+
+.foundation-form-section legend {
+    padding-inline: var(--foundation-space-2);
+    font-weight: 700;
+}
+
+.foundation-form-grid {
+    display: grid;
+    gap: var(--foundation-space-3);
+}
+
+.foundation-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-1);
+    min-inline-size: 0;
+}
+
+.foundation-field-label {
+    font-weight: 600;
+}
+
+.foundation-required {
+    color: var(--foundation-danger);
+}
+
+.foundation-field-error {
+    color: var(--foundation-danger);
+    font-size: 0.875rem;
+}
+
+.foundation-field[data-invalid] input,
+.foundation-field[data-invalid] select,
+.foundation-field[data-invalid] textarea {
+    border-color: var(--foundation-danger);
+}
+
+.foundation-field textarea,
+.foundation-field input[type='file'] {
+    padding: var(--foundation-space-2);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+    color: var(--foundation-text);
+    font: inherit;
+}
+
+.foundation-fieldset {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--foundation-space-3);
+    margin: 0;
+    padding: 0;
+    border: 0;
+}
+
+.foundation-address {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: var(--foundation-space-2);
+}
+
+.foundation-form-actions {
+    position: sticky;
+    inset-block-end: 0;
+    background: var(--foundation-surface);
+}
+
+@media (max-width: 40rem) {
+    .foundation-form-grid {
+        grid-template-columns: minmax(0, 1fr) !important;
+    }
+
+    .foundation-field {
+        grid-column: auto !important;
+    }
+}