@nubisco/ui 3.2.0 → 3.3.0

package/dist/components/NotificationCenter.d.ts

@@ -0,0 +1,184 @@
+import type { IAnchorSize } from '../utils/anchorPosition.helper'
+import type { TNotificationVariant } from './NotificationCenterItem.d'
+
+export interface INotificationItem {
+  /** Stable key. Reused across refetches so the list does not re-mount. */
+  id: string | number
+  title: string
+  body?: string
+  /** ISO string, epoch milliseconds or a Date. */
+  time?: string | number | Date
+  /** Pre-formatted time, when the host already has one it likes. */
+  timeLabel?: string
+  read?: boolean
+  /** Status word, from the same vocabulary as NbToast and NbMessage. */
+  variant?: TNotificationVariant
+  icon?: string | null
+  /** Renders the row as a link instead of a button. */
+  href?: string
+  /** Overrides the centre's `interactive` for this one row. `false` makes
+   *  the row inert: read, not pressed. */
+  interactive?: boolean
+}
+
+/**
+ * Everything a replacement trigger has to carry for the panel to be
+ * announced correctly. Handed to the `#trigger` slot and meant to be spread
+ * onto whatever element the host renders:
+ *
+ * ```vue
+ * <template #trigger="{ triggerProps, setTriggerRef, toggle, unreadCount }">
+ *   <NbButton :ref="setTriggerRef" v-bind="triggerProps" @click="toggle" />
+ * </template>
+ * ```
+ *
+ * The centre cannot generate these ids for a host it never sees, and a host
+ * cannot guess them, so they are passed rather than documented. `aria-label`
+ * is a default, not a mandate: bind it after the spread to replace it.
+ */
+export interface INotificationTriggerProps {
+  id: string
+  'aria-haspopup': 'dialog'
+  'aria-expanded': 'true' | 'false'
+  'aria-controls': string | undefined
+  'aria-label': string
+  disabled: boolean | undefined
+}
+
+/**
+ * Everything the built-in mark-all control binds, as one object, handed to
+ * the `#header-actions` slot. A host that replaces the header still gets the
+ * pending-safe behaviour (aria-disabled rather than disabled so the in-flight
+ * button keeps focus, aria-busy, and a second click that is swallowed instead
+ * of firing a second request the host cannot cancel) by spreading this onto
+ * its own button rather than re-deriving it:
+ *
+ * ```vue
+ * <template #header-actions="{ markAllProps, markAllText }">
+ *   <MyFilter v-model="filter" />
+ *   <button v-bind="markAllProps">{{ markAllText }}</button>
+ * </template>
+ * ```
+ *
+ * `onClick` is included, so `v-bind` attaches the handler with it.
+ */
+export interface INotificationMarkAllProps {
+  type: 'button'
+  disabled: boolean
+  'aria-disabled': 'true' | undefined
+  'aria-busy': 'true' | undefined
+  onClick: () => void
+}
+
+export interface INotificationCenterProps {
+  /** The rows. Omit it and use the default slot when the shape of a
+   *  notification is more than a title, a body and a time. */
+  items?: INotificationItem[]
+  /** Authoritative unread total, for products that page the list and know a
+   *  server-side count larger than what is loaded. Defaults to counting
+   *  `items` where `read` is not true. */
+  unreadCount?: number
+  /**
+   * How many rows are on screen. Required alongside `unreadCount` whenever
+   * you fill the default slot, optional otherwise (with `items` the centre
+   * counts the array).
+   *
+   * The centre renders your slot, it does not read it, so it cannot tell an
+   * empty feed from a slot you chose not to fill. Without this number the
+   * `#empty` state cannot render at all, and `error` resolves to the full
+   * error region rather than the stale-data strip, because a failure that
+   * might be hiding behind rows is the one thing this component exists to
+   * prevent. A dev-mode warning is printed the first time a panel opens in
+   * that configuration.
+   */
+  itemCount?: number
+  /** Optional `v-model:open`. Left undefined the centre owns its own state. */
+  open?: boolean
+  /** Names the trigger and titles the panel. */
+  label?: string
+  markAllLabel?: string
+  /** Shown, and announced, while `markAllPending` is true. Present tense. */
+  markAllPendingLabel?: string
+  /** The host's mark-all request is in flight. The control keeps focus and
+   *  stops accepting clicks rather than firing the request again. */
+  markAllPending?: boolean
+  emptyTitle?: string
+  emptyDescription?: string
+  /** Announced while `loading` is true. */
+  loadingLabel?: string
+  /** Renders placeholder rows instead of the list, the empty state or the
+   *  error state. A request that has not finished is not a result. */
+  loading?: boolean
+  /**
+   * The fetch failed. This is a state of its own and not a flavour of empty:
+   * the audit that motivated this component found an app whose single
+   * `.empty-text` rendered both, so a failed request read as "no contacts
+   * yet". With no rows to show, the panel renders the error state; with rows
+   * already on screen it keeps them and says the refresh failed, because
+   * stale notifications beat no notifications.
+   */
+  error?: boolean
+  errorTitle?: string
+  errorDescription?: string
+  /** Shown on the stale strip when a refresh fails over rows already loaded. */
+  errorStaleLabel?: string
+  retryLabel?: string
+  /** Offer a retry control with the error state. Turn it off when the host
+   *  retries on its own and a button would be a lie. */
+  showRetry?: boolean
+  /** Counts above this render as "n+" on the badge. */
+  maxCount?: number
+  /** Panel width in px. */
+  width?: number
+  /** Tallest the scrolling list may get, in px. Clamped further when the
+   *  viewport is shorter than that. */
+  maxHeight?: number
+  /** Which trigger edge the panel lines up with. */
+  align?: 'start' | 'end'
+  showMarkAll?: boolean
+  /**
+   * Whether rows are activatable. `false` renders genuinely inert rows: no
+   * tabindex, no place in the roving focus, no `select`. Right for a feed
+   * with nowhere to go, and when every row is inert the scrolling list
+   * becomes the tab stop so a keyboard can still reach the bottom of it.
+   */
+  interactive?: boolean
+  closeOnSelect?: boolean
+  /** Close when the page navigates (history back/forward, a hash change, or
+   *  any navigation the browser reports through the Navigation API). */
+  closeOnNavigate?: boolean
+  disabled?: boolean
+  /** Phosphor icon for the trigger and the empty state. */
+  icon?: string
+  /** BCP 47 tag for relative times. */
+  locale?: string
+  unreadLabel?: string
+  readLabel?: string
+  /** Builds the unread half of the trigger's accessible name. Replace it to
+   *  translate or to pluralise the way your language actually does. */
+  formatUnread?: (count: number) => string
+}
+
+export interface IPanelPlacementOptions {
+  align: 'start' | 'end'
+  /** Panel width in px. */
+  width: number
+  /** Tallest the scrolling list may get. */
+  maxHeight: number
+  viewport: IAnchorSize
+}
+
+export interface IPanelPlacement {
+  /** Viewport (`position: fixed`) coordinates. */
+  top: number
+  left: number
+  /** The side actually used, after any flip. */
+  side: 'top' | 'bottom'
+  /** What the list may scroll to before it clips, after the viewport clamp. */
+  maxListHeight: number
+}
+
+/* The placement arithmetic itself (`placeNotificationPanel`,
+ * `isAnchorInViewport`) is runtime code and therefore lives in
+ * NotificationCenter.vue, which is where it is imported from. Only its
+ * argument and result shapes are declared here. */

package/dist/components/NotificationCenter.vue.d.ts

@@ -0,0 +1,130 @@
+import type { INotificationCenterProps, INotificationItem, INotificationMarkAllProps, INotificationTriggerProps } from './NotificationCenter.d';
+import type { IAnchorRect, IAnchorSize } from '../utils/anchorPosition.helper';
+import type { IPanelPlacement, IPanelPlacementOptions } from './NotificationCenter.d';
+export type { INotificationItem, INotificationTriggerProps, INotificationMarkAllProps, INotificationCenterProps, } from './NotificationCenter.d';
+export type { IPanelPlacement, IPanelPlacementOptions };
+export declare function placeNotificationPanel(anchor: IAnchorRect, { align, width, maxHeight, viewport }: IPanelPlacementOptions): IPanelPlacement;
+/**
+ * Whether any part of the trigger is still on screen. A panel is fixed to the
+ * viewport, so once the bell it belongs to has scrolled away the panel is
+ * floating over content it has nothing to do with, and the honest thing is to
+ * let go of it.
+ */
+export declare function isAnchorInViewport(anchor: IAnchorRect, viewport: IAnchorSize): boolean;
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<INotificationCenterProps, {
+    show: () => void;
+    close: (options?: {
+        restoreFocus?: boolean;
+    }) => void;
+    toggle: () => void;
+    isOpen: import("vue").ComputedRef<boolean>;
+    unreadCount: import("vue").ComputedRef<number>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (item: INotificationItem | null, event: Event) => any;
+    close: () => any;
+    open: () => any;
+    "update:open": (value: boolean) => any;
+    "mark-all-read": () => any;
+    retry: () => any;
+}, string, import("vue").PublicProps, Readonly<INotificationCenterProps> & Readonly<{
+    onSelect?: ((item: INotificationItem | null, event: Event) => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onOpen?: (() => any) | undefined;
+    "onUpdate:open"?: ((value: boolean) => any) | undefined;
+    "onMark-all-read"?: (() => any) | undefined;
+    onRetry?: (() => any) | undefined;
+}>, {
+    align: "start" | "end";
+    disabled: boolean;
+    label: string;
+    icon: string;
+    maxHeight: number;
+    width: number;
+    error: boolean;
+    items: INotificationItem[];
+    loading: boolean;
+    locale: string;
+    open: boolean;
+    interactive: boolean;
+    unreadLabel: string;
+    readLabel: string;
+    unreadCount: number;
+    itemCount: number;
+    markAllLabel: string;
+    markAllPendingLabel: string;
+    markAllPending: boolean;
+    emptyTitle: string;
+    emptyDescription: string;
+    loadingLabel: string;
+    errorTitle: string;
+    errorDescription: string;
+    errorStaleLabel: string;
+    retryLabel: string;
+    showRetry: boolean;
+    maxCount: number;
+    showMarkAll: boolean;
+    closeOnSelect: boolean;
+    closeOnNavigate: boolean;
+    formatUnread: (count: number) => string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    trigger?: (props: {
+        open: boolean;
+        toggle: () => void;
+        show: () => void;
+        close: (options?: {
+            restoreFocus?: boolean;
+        }) => void;
+        unreadCount: number;
+        badge: string;
+        panelId: string;
+        triggerProps: INotificationTriggerProps;
+        setTriggerRef: (value: Element | {
+            $el?: unknown;
+        } | null) => void;
+    }) => any;
+} & {
+    'header-start'?: (props: {
+        close: (options?: {
+            restoreFocus?: boolean;
+        }) => void;
+        unreadCount: number;
+    }) => any;
+} & {
+    'header-actions'?: (props: {
+        close: (options?: {
+            restoreFocus?: boolean;
+        }) => void;
+        unreadCount: number;
+        markAllRead: () => void;
+        markAllPending: boolean;
+        markAllProps: INotificationMarkAllProps;
+        markAllText: string;
+    }) => any;
+} & {
+    error?: (props: {
+        retry: () => void;
+    }) => any;
+} & {
+    default?: (props: {
+        close: (options?: {
+            restoreFocus?: boolean;
+        }) => void;
+        items: INotificationItem[];
+    }) => any;
+} & {
+    empty?: (props: {}) => any;
+} & {
+    footer?: (props: {
+        close: (options?: {
+            restoreFocus?: boolean;
+        }) => void;
+    }) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+//# sourceMappingURL=NotificationCenter.vue.d.ts.map

package/dist/components/NotificationCenter.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationCenter.vue.d.ts","sourceRoot":"","sources":["../../src/components/NotificationCenter.vue"],"names":[],"mappings":"AAk5CA,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAA;AAG/B,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAC7E,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAK/B,YAAY,EACV,iBAAiB,EACjB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,CAAA;AAuCvD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,WAAW,EACnB,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAC5D,eAAe,CA4BjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAOT;wBACoB,OAAO,YAAY;AAAxC,wBAAyC;AACzC,QAAA,MAAM,YAAY;;sBAgSM;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAo6BpC,CAAC,KAAK;;;;0BAp6BI;YAAE,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE;;;;;+BAvEpB,OAAO,GAAG;YAAE,GAAG,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,KAAG,IAAI;KA2+BnC,KAAK,GAAG;;qBACvB,CAAC,KAAK;0BAr6BH;YAAE,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE;;KAq6BN,KAAK,GAAG;;uBAC7B,CAAC,KAAK;0BAt6BL;YAAE,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE;;;;;;KAs6BJ,KAAK,GAAG;;YAC1C,CAAC,KAAK;;KAAiB,KAAK,GAAG;;cAC7B,CAAC,KAAK;0BAx6BI;YAAE,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE;;KAw6Bb,KAAK,GAAG;;YACjC,CAAC,KAAK,IAAiB,KAAK,GAAG;;aAC9B,CAAC,KAAK;0BA16BK;YAAE,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE;KA06Bd,KAAK,GAAG;EAgBxC,CAAC;AAWL,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/components/NotificationCenterItem.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The fleet's status vocabulary, the same five words NbToast, NbMessage and
+ * NbBanner use. `error`, not `danger`: `danger` is the word for a destructive
+ * ACTION (NbButton, NbConfirm), and the audit found an app passing
+ * variant="danger" to NbMessage, which does not accept it, precisely because
+ * the two vocabularies had drifted. `danger` is accepted here and treated as
+ * `error` so that app's habit does not silently render an unstyled row, but it
+ * is deprecated and not the documented value.
+ */
+export type TNotificationStatus =
+  | 'neutral'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'error'
+
+/** @deprecated Use TNotificationStatus. */
+export type TNotificationVariant = TNotificationStatus | 'danger'
+
+export interface INotificationCenterItemProps {
+  /** Headline of the notification. One line, no trailing punctuation. */
+  title?: string
+  /** Supporting sentence. Wraps to at most three lines before it is clipped. */
+  body?: string
+  /** When the event happened. Rendered as a `<time>` with a machine-readable
+   *  `datetime`, and formatted relative to now unless `timeLabel` is given. */
+  time?: string | number | Date
+  /** A ready-made time string. Use it when the host app already formats
+   *  timestamps its own way, and this component should not second-guess it. */
+  timeLabel?: string
+  /** Read notifications lose the dot, the tint and the heavier title. */
+  read?: boolean
+  /** Colours the leading icon. It does not change the unread affordance,
+   *  which stays one shape everywhere so it can be learned once. Values are
+   *  the library's status words: neutral, info, success, warning, error. */
+  variant?: TNotificationVariant
+  /** Phosphor icon name. `null` renders no icon and no icon gutter. */
+  icon?: string | null
+  /** Renders the row as a link. Takes priority over `interactive`. */
+  href?: string
+  /**
+   * A row that leads somewhere is a `<button>` (or an `<a>`, with `href`).
+   * A row that leads nowhere is `false` here, and then it is genuinely inert:
+   * a plain element with no tabindex, outside the panel's roving focus, and
+   * it never emits `select`. Not "a button that looks quieter".
+   */
+  interactive?: boolean
+  /** BCP 47 tag for the relative time. Defaults to the runtime locale. */
+  locale?: string
+  /** Visually hidden state words, translated by the host. */
+  unreadLabel?: string
+  readLabel?: string
+}

package/dist/components/NotificationCenterItem.vue.d.ts

@@ -0,0 +1,36 @@
+import type { INotificationCenterItemProps } from './NotificationCenterItem.d';
+export type { TNotificationStatus, TNotificationVariant, INotificationCenterItemProps, } from './NotificationCenterItem.d';
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<INotificationCenterItemProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (event: Event) => any;
+}, string, import("vue").PublicProps, Readonly<INotificationCenterItemProps> & Readonly<{
+    onSelect?: ((event: Event) => any) | undefined;
+}>, {
+    body: string;
+    time: string | number | Date;
+    title: string;
+    icon: string | null;
+    variant: import("./NotificationCenterItem.d").TNotificationVariant;
+    href: string;
+    locale: string;
+    timeLabel: string;
+    read: boolean;
+    interactive: boolean;
+    unreadLabel: string;
+    readLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    media?: (props: {}) => any;
+} & {
+    title?: (props: {}) => any;
+} & {
+    default?: (props: {}) => any;
+} & {
+    actions?: (props: {}) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+//# sourceMappingURL=NotificationCenterItem.vue.d.ts.map

package/dist/components/NotificationCenterItem.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationCenterItem.vue.d.ts","sourceRoot":"","sources":["../../src/components/NotificationCenterItem.vue"],"names":[],"mappings":"AA+aA,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,4BAA4B,CAAA;AAOnC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,4BAA4B,CAAA;wBACd,OAAO,YAAY;AAAxC,wBAAyC;AACzC,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;YA0SN,CAAC,KAAK,IAAgB,KAAK,GAAG;;YAC9B,CAAC,KAAK,IAAiB,KAAK,GAAG;;cAC7B,CAAC,KAAK,IAAiB,KAAK,GAAG;;cAC/B,CAAC,KAAK,IAAiB,KAAK,GAAG;EAWzC,CAAC;AAWL,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/components/ProgressBar.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProgressBar.vue.d.ts","sourceRoot":"","sources":["../../src/components/ProgressBar.vue"],"names":[],"mappings":"AAkMA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AAgKxB,QAAA,MAAM,YAAY;;;;;;;6EAGhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}
+{"version":3,"file":"ProgressBar.vue.d.ts","sourceRoot":"","sources":["../../src/components/ProgressBar.vue"],"names":[],"mappings":"AAyNA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AAgKxB,QAAA,MAAM,YAAY;;;;;;;6EAGhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}

package/dist/components/Shell.d.ts

@@ -1,9 +1,25 @@
 type TInspectorSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 type TSidebarVariant = 'compact' | 'verbose'
+type TShellTopbar = 'auto' | 'always' | 'never'
+type TShellCollapseAt = 'md' | 'lg' | 'none'
 
 interface IShellProps {
   /**
    * Whether the inspector column is visible.
+   *
+   * Controlled or uncontrolled, on the same rule as `sidebarOpen` and
+   * `inspectorWidth`: pass it (as `v-model:inspector-visible`) and the
+   * application owns the state, leave it out and the shell owns it. Either way
+   * `update:inspectorVisible` is emitted when the shell closes the inspector
+   * itself, which happens on Escape and on the sheet's dismiss button below
+   * `collapseAt`.
+   *
+   * The shell will always be able to close its own sheet: a shell given
+   * `:inspector-visible="true"` with nothing listening for the update still
+   * hides the overlay locally rather than leaving the user trapped behind it.
+   * That override is scoped to the overlay and clears itself as soon as the
+   * application sets the prop true again or the frame stops collapsing, so the
+   * desktop column is untouched by it.
    * @default false
    */
   inspectorVisible?: boolean
@@ -24,19 +40,32 @@ interface IShellProps {
    */
   inspectorSize?: TInspectorSize
   /**
-   * Allow the user to resize the inspector by dragging its left edge, clamped
-   * between the `inspectorSize` width (the floor) and 50% of the viewport.
+   * Allow the user to resize the inspector by dragging its left edge (or by
+   * focusing the handle and using the arrow keys), clamped between 288px (the
+   * floor) and 50% of the current viewport. The upper clamp is re-evaluated
+   * when the window resizes, so a width persisted on a wide monitor cannot
+   * squeeze the body on a narrow one.
    * Double-clicking the handle resets to the `inspectorSize` default. Pair with
-   * `v-model:inspector-width` to persist the chosen width.
+   * `v-model:inspector-width` to persist the chosen width; without it the shell
+   * keeps the width itself, so `resizable` alone is a working control rather
+   * than a handle that moves nothing.
    * @default false
    */
   resizable?: boolean
   /**
    * The user-chosen inspector width in pixels when `resizable` is on, as a
-   * v-model (`v-model:inspector-width`). `null` (the default / reset state)
-   * means "use the `inspectorSize` width". The component emits
-   * `update:inspectorWidth` on drag and on double-click reset; the consumer
-   * owns persistence.
+   * v-model (`v-model:inspector-width`). `null` means "use the `inspectorSize`
+   * width", which is what a reset emits.
+   *
+   * Controlled or uncontrolled, decided once at setup by whether the prop was
+   * passed at all:
+   *
+   * - passed (including as `null`): the application owns the width and the
+   *   shell renders exactly what it is given. `update:inspectorWidth` is
+   *   emitted on drag, on the arrow keys and on reset.
+   * - omitted: the shell owns the width internally. The handle still works and
+   *   still emits, so an application can listen without binding, but nothing
+   *   has to be stored for the drag to do anything.
    */
   inspectorWidth?: number | null
   /**
@@ -55,6 +84,107 @@ interface IShellProps {
    * @default 'compact'
    */
   sidebarVariant?: TSidebarVariant
+  /**
+   * When the topbar strip is rendered.
+   *
+   * - 'auto': rendered only when `topbar-left` or `topbar-right` has content,
+   *   or a view has claimed one of them with `useShellSlot()`. An application
+   *   that passes neither gets no empty 50px bar and no border line to hide
+   *   from the outside.
+   * - 'always': rendered unconditionally. This is what the shell did before
+   *   the check existed; set it if a layout depends on the bar's height being
+   *   reserved even while it is empty.
+   * - 'never': never rendered, whatever the slots say. For a full-bleed route
+   *   inside an application whose shell is declared once, further up.
+   *
+   * @default 'auto'
+   */
+  topbar?: TShellTopbar
+  /**
+   * Render the "skip to content" link as the shell's first focusable element.
+   *
+   * The shell is the only component that knows where the main region is, so it
+   * is the only one that can wire a skip link without the application inventing
+   * an id. It is visually hidden until focused, so the first Tab on any page
+   * offers it and nothing else changes.
+   *
+   * Set to `false` only if the application already ships its own.
+   * @default true
+   */
+  skipToContent?: boolean
+  /**
+   * Label for the skip link. Override for a localised application.
+   * @default 'Skip to content'
+   */
+  skipToContentLabel?: string
+  /**
+   * The `id` put on the `<main>` element, and the skip link's target. Set it
+   * when something outside the shell needs to address the main region by a
+   * known id (a router scroll behaviour, an `aria-controls`). Defaults to a
+   * per-instance stable id, so two shells on one page do not collide.
+   */
+  mainId?: string
+  /**
+   * Accessible name for the sidebar `<nav>` landmark. Two navigation landmarks
+   * on a page (the rail plus in-page nav) are indistinguishable in a landmark
+   * list without one.
+   * @default 'Primary'
+   */
+  sidebarLabel?: string
+  /**
+   * Accessible name for the inspector `<aside>` landmark.
+   * @default 'Inspector'
+   */
+  inspectorLabel?: string
+  /**
+   * The viewport width below which the frame stops being three columns.
+   *
+   * A 240px verbose rail plus a 288px inspector leaves nothing for the page on
+   * a phone, and the frame is `height: 100dvh; overflow: hidden`, so there is
+   * no scroll to escape into. Below this width the sidebar becomes an overlay
+   * drawer behind a toggle button and the inspector becomes a full-screen
+   * sheet over the content row, topbar included, carrying its own dismiss
+   * button. The same thing happens at 200% browser zoom on a
+   * laptop, because zoom shrinks the viewport in CSS pixels, which is the
+   * WCAG 1.4.10 reflow case.
+   *
+   * - 'md': collapse below 672px. The default.
+   * - 'lg': collapse below 1056px. For products whose rail is verbose and
+   *   whose inspector is usually open.
+   * - 'none': never collapse. The pre-3.3 layout, for a frame that is only
+   *   ever shown on a desktop (an installed desktop build, a control room).
+   *
+   * @default 'md'
+   */
+  collapseAt?: TShellCollapseAt
+  /**
+   * Whether the navigation drawer is open at collapsed widths. Optional: pass
+   * it (as `v-model:sidebar-open`) to drive the drawer from the application,
+   * leave it out and the shell owns the state itself. Ignored above
+   * `collapseAt`, where the sidebar is a permanent column.
+   */
+  sidebarOpen?: boolean
+  /**
+   * Accessible name for the button that opens the navigation drawer. The
+   * button carries `aria-expanded`, so the label should name the thing, not
+   * the action: "Navigation", not "Open navigation".
+   * @default 'Navigation'
+   */
+  navToggleLabel?: string
+  /**
+   * Accessible name for the button that closes the inspector sheet below
+   * `collapseAt`. The button is rendered only in that overlay state, where the
+   * sheet covers the topbar and therefore any close control the product put
+   * there.
+   * @default 'Close inspector'
+   */
+  inspectorCloseLabel?: string
 }
 
-export { IShellProps, TInspectorSize, TSidebarVariant }
+export {
+  IShellProps,
+  TInspectorSize,
+  TSidebarVariant,
+  TShellTopbar,
+  TShellCollapseAt,
+}

package/dist/components/Shell.vue.d.ts

@@ -1,4 +1,6 @@
-import { IShellProps } from './Shell.d';
+import { IShellProps, TInspectorSize } from './Shell.d';
+declare function setDrawerOpen(open: boolean): void;
+declare function setInspectorVisible(visible: boolean): void;
 declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {}, __VLS_15: {}, __VLS_17: {}, __VLS_19: {}, __VLS_27: {}, __VLS_29: {}, __VLS_31: {};
 type __VLS_Slots = {} & {
     'outer-menu'?: (props: typeof __VLS_1) => any;
@@ -27,17 +29,42 @@ type __VLS_Slots = {} & {
 } & {
     inspector?: (props: typeof __VLS_31) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<IShellProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<IShellProps, {
+    /** The `<main>` element, so a parent can scroll or measure the page ground. */
+    mainEl: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+    /** The sidebar `<nav>`, or null when no sidebar slot has content. */
+    sidebarEl: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+    /** The inspector `<aside>`. Always present; it animates from zero width. */
+    inspectorEl: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+    /** Move focus to the main region, exactly as the skip link does. */
+    focusMain: () => void | undefined;
+    /** Open or close the navigation drawer. No-op above `collapseAt`. */
+    setSidebarOpen: typeof setDrawerOpen;
+    /** Show or hide the inspector, and emit `update:inspectorVisible`. */
+    setInspectorVisible: typeof setInspectorVisible;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:inspectorWidth": (width: number | null) => any;
+    "update:sidebarOpen": (open: boolean) => any;
+    "update:inspectorVisible": (visible: boolean) => any;
 }, string, import("vue").PublicProps, Readonly<IShellProps> & Readonly<{
     "onUpdate:inspectorWidth"?: ((width: number | null) => any) | undefined;
+    "onUpdate:sidebarOpen"?: ((open: boolean) => any) | undefined;
+    "onUpdate:inspectorVisible"?: ((visible: boolean) => any) | undefined;
 }>, {
     inspectorVisible: boolean;
     inspectorExpanded: boolean;
-    inspectorSize: import("./Shell.d").TInspectorSize;
+    inspectorSize: TInspectorSize;
     resizable: boolean;
     mainPadding: boolean;
     sidebarVariant: import("./Shell.d").TSidebarVariant;
+    topbar: import("./Shell.d").TShellTopbar;
+    skipToContent: boolean;
+    skipToContentLabel: string;
+    sidebarLabel: string;
+    inspectorLabel: string;
+    collapseAt: import("./Shell.d").TShellCollapseAt;
+    navToggleLabel: string;
+    inspectorCloseLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/Shell.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Shell.vue.d.ts","sourceRoot":"","sources":["../../src/components/Shell.vue"],"names":[],"mappings":"AAklBA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AA2WvC,QAAA,IAAI,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAY,CAAE;AAC5Q,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACjD;IAAE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACnD;IAAE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GAClD;IAAE,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACrD;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACjD;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAClD;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC7C;IAAE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GACnD;IAAE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC9C;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC7C;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC5C;IAAE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAOlD,QAAA,MAAM,UAAU;;;;;;;;;;;6EAId,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}
+{"version":3,"file":"Shell.vue.d.ts","sourceRoot":"","sources":["../../src/components/Shell.vue"],"names":[],"mappings":"AAoqDA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAuSvD,iBAAS,aAAa,CAAC,IAAI,EAAE,OAAO,QAGnC;AA2FD,iBAAS,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAQ5C;AA0yBD,QAAA,IAAI,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,OAAO,IAAU,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAW,EAAE,QAAQ,IAAY,CAAE;AAC5Q,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACjD;IAAE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACnD;IAAE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GAClD;IAAE,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACrD;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACjD;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAClD;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC7C;IAAE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GACnD;IAAE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC9C;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC7C;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,GAC5C;IAAE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAWlD,QAAA,MAAM,UAAU;IArcd,+EAA+E;;IAE/E,qEAAqE;;IAErE,4EAA4E;;IAE5E,oEAAoE;;IAEpE,qEAAqE;;IAErE,sEAAsE;;;;;;;;;;;;;;;;;;;;;;;;;6EAgctE,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}