@octans/ui 1.0.0

package/dist/components/Modal/api/types.d.ts

@@ -0,0 +1,110 @@
+import { VNode } from 'vue';
+import { ActionType, ActionTypeType } from '../../types';
+/**
+ * Types for the imperative modal API — `alertModal()`, `confirmModal()`,
+ * `promptModal()` and `genericModal()` — as opposed to `ModalProps`, which
+ * describes the `<Modal>` component.
+ *
+ * These lived in a `namespace Api` inside `../types.ts`. The file is the
+ * namespace now, and which spelling a caller uses depends on where it sits:
+ *
+ * - Outside this folder, `import type * as Api from './api/types'` and write
+ *   `Api.AlertModalOptions`. The prefix is what tells them apart from
+ *   `ModalProps`, which belongs to the `<Modal>` component rather than to any
+ *   of this.
+ * - Inside this folder, import the names directly — you are already here, and
+ *   the `.vue` files have no choice: `defineProps<T>()` is resolved by
+ *   `@vue/compiler-sfc` rather than by TypeScript, and it cannot follow a
+ *   namespace-import alias. `defineProps<Api.AlertModalProps>()` compiles
+ *   under `vue-tsc` and then fails at build time with "Unresolvable type
+ *   reference".
+ */
+export interface BaseProps {
+    visible: boolean;
+}
+export interface GenericModalProps extends BaseProps {
+    opts: GenericModalOptions;
+}
+export interface ConfirmModalProps extends BaseProps {
+    opts: ConfirmModalOptions;
+}
+export interface AlertModalProps extends BaseProps {
+    opts: AlertModalOptions;
+}
+export interface PromptModalProps extends BaseProps {
+    opts: PromptModalOptions;
+}
+export interface ModalOptions {
+    title?: string;
+    onAction?(value?: string): void;
+}
+export interface AlertModalOptions extends ModalOptions {
+    primaryActionLabel?: string;
+    primaryActionType?: ActionTypeType;
+    content?: string | VNode;
+}
+export interface ConfirmModalOptions extends ModalOptions {
+    primaryActionLabel?: string;
+    primaryActionType?: ActionTypeType;
+    secondaryActionLabel?: string;
+    content?: string | VNode;
+    onConfirm?(): void;
+    onCancel?(): void;
+}
+export interface GenericModalOptions extends ModalOptions {
+    content?: string | VNode;
+    primaryAction?: ModalActionType;
+    secondaryActions?: ModalActionType[];
+}
+export interface PromptModalOptions extends ModalOptions {
+    content?: string | VNode;
+    /**
+     * @default "Submit"
+     */
+    primaryActionLabel?: string;
+    /**
+     * @default "Cancel"
+     */
+    secondaryActionLabel?: string;
+    /**
+     * The default value of the input.
+     */
+    inputValue?: string;
+    /**
+     * If set to `true` the input will be a textarea instead of a single line. Pressing enter will create a new line instead of submitting. If you press Command+Enter (MacOS) or Control+Enter (Windows) the prompt will submit.
+     */
+    multiline?: boolean;
+    /**
+     * Help text below the input.
+     */
+    inputHelpText?: string;
+    /**
+     * The placeholder text for the input.
+     */
+    inputPlaceholder?: string;
+    /**
+     * Error message to show below input when `inputValidator` returns `false`
+     * (to signify an error but without any specific error message).
+     *
+     * @default "Invalid value."
+     */
+    invalidValueText?: string;
+    /**
+     * Return `true` if the input is valid.
+     * Return `false` if invalid.
+     * Return a string to use as invalid error message.
+     *
+     * @default Defaults to a function that prevents empty strings or input
+     * that is pure whitespace.
+     */
+    inputValidator?(input: string): boolean | string;
+    onSubmit?(value: string): void;
+    onCancel?(): void;
+}
+export interface ModalActionType extends ActionType {
+    id?: string;
+}
+export interface ModalEmits {
+    (e: 'action', result?: string | boolean): void;
+    (e: 'afterLeave'): void;
+}

package/dist/components/Modal/host.d.ts

@@ -0,0 +1,2 @@
+export declare function teardownHost(): void;
+export declare function ensureHost(): void;

package/dist/components/Modal/index.d.ts

@@ -0,0 +1,10 @@
+import { default as Modal } from './Modal.vue';
+import { default as ModalHost } from './ModalHost.vue';
+import type * as Api from './api/types';
+export declare const genericModal: <Result = unknown>(opts: Api.GenericModalOptions) => Promise<Result | undefined>;
+export declare const alertModal: <Result = unknown>(opts: Api.AlertModalOptions) => Promise<Result | undefined>;
+export declare const confirmModal: <Result = boolean>(opts: Api.ConfirmModalOptions) => Promise<Result | undefined>;
+export declare const promptModal: <Result = string>(opts: Api.PromptModalOptions) => Promise<Result | undefined>;
+export { Modal, ModalHost };
+export type { ModalProps } from './types';
+export type { ModalOptions, ModalActionType, AlertModalOptions, ConfirmModalOptions, GenericModalOptions, PromptModalOptions } from './api/types';

package/dist/components/Modal/manager.d.ts

@@ -0,0 +1,80 @@
+import { Component, ComputedRef } from 'vue';
+import type * as Api from './api/types';
+/**
+ * One open modal. `alertModal()` and friends push one of these and hand back a
+ * promise; `<ModalHost>` renders whatever is in the array.
+ */
+export interface ModalEntry {
+    id: number;
+    /** `AlertModal`, `ConfirmModal`, … — always `markRaw`d. */
+    component: Component;
+    opts: Api.ModalOptions;
+    /** Drives the enter/leave transition. Setting it false starts the close. */
+    visible: boolean;
+    /**
+     * Closes this modal the way its own "X" button would — so a confirm resolves
+     * `false` rather than `undefined`. Registered by the `<Modal>` inside, since
+     * only it knows what closing means for that flavour.
+     */
+    requestClose?: () => void;
+    /** Focuses this modal's dialog. Registered by the `<Modal>` inside. */
+    focus?: () => void;
+}
+export interface ModalStackContext {
+    /** 0 for the first modal open, 1 for one opened on top of it, and so on. */
+    depth: ComputedRef<number>;
+    register: (handlers: {
+        requestClose: () => void;
+        focus: () => void;
+    }) => void;
+}
+/** Present when a `<Modal>` is being rendered by a `<ModalHost>`. */
+export declare const MODAL_STACK: unique symbol;
+export declare class ModalManager {
+    nextId: number;
+    entries: ModalEntry[];
+    /** How many `<ModalHost>`s are currently rendering these entries. */
+    hosts: number;
+    private settled;
+    private resolvers;
+    private hostWatchers;
+    constructor();
+    add(component: Component, opts: Api.ModalOptions, resolve: (result?: any) => void): ModalEntry;
+    /** Starts the enter transition. Entries are added hidden. */
+    show(id: number): void;
+    /** Starts the leave transition. The entry goes when the transition ends. */
+    hide(id: number): void;
+    /**
+     * How a `<Modal>` hands back the two things the host cannot work out for
+     * itself: what closing means for this flavour of modal, and how to focus it.
+     */
+    register(id: number, handlers: {
+        requestClose: () => void;
+        focus: () => void;
+    }): void;
+    /**
+     * Resolves the promise the API handed back. Called on the action, and again
+     * as a backstop when the modal leaves — a modal that goes away without an
+     * action still has to settle rather than leave its caller awaiting forever.
+     */
+    settle(id: number, result?: any): void;
+    remove(id: number): void;
+    /**
+     * The modal ESC should close and focus should return to — the last one that
+     * is not already on its way out.
+     */
+    get top(): ModalEntry | undefined;
+    addHost(): void;
+    removeHost(): void;
+    watchHosts(fn: () => void): () => void;
+}
+/**
+ * The open modals, shared by every `<ModalHost>`.
+ *
+ * Each imperative modal used to be its own `createApp` in its own container,
+ * which made them independent but left them unable to coordinate: N modals drew
+ * N backdrops that compounded into a darker and darker page, stacked at exactly
+ * the same coordinates, and each added its own window-level ESC listener, so one
+ * Escape closed all of them at once.
+ */
+export declare const modals: ModalManager;

package/dist/components/Modal/types.d.ts

@@ -0,0 +1,49 @@
+import type * as Api from './api/types';
+export interface ModalProps {
+    visible: boolean;
+    title?: string;
+    /**
+     * Options for the primary action button.
+     */
+    primaryAction?: Api.ModalActionType;
+    /**
+     * An array of options for the secondary actions.
+     */
+    secondaryActions?: Api.ModalActionType[];
+    /**
+     * An array of options for the tertiary actions. These will show on the left side of the footer.
+     */
+    tertiaryActions?: Api.ModalActionType[];
+    /**
+     * Shows a spinner over the whole modal dialog and prevents closing.
+     */
+    loading?: boolean;
+    /**
+     * Does not render header section
+     */
+    noHeader?: boolean;
+    /**
+     * Style to add to the dialog element, e.g. to set a width, height
+     */
+    dialogStyle?: Record<string, any>;
+    /**
+     * Styles for the pre-body slot.
+     */
+    preBodyStyle?: Record<string, any>;
+    /**
+     * Styles for the body slot.
+     */
+    bodyStyle?: Record<string, any>;
+    /**
+     * Workaround to allow modal body overflow to be visible.
+     * Used to prevent popper items that do not use teleport within the modal from being clipped.
+     */
+    overflowVisible?: boolean;
+    /**
+     * Invoked when the modal's "X" button is clicked or ESC is pressed. The "X"
+     * button and the ESC handler are only rendered when this is defined.
+     * NOTE: `@close` compiles down to this same prop, which is why there is no
+     * matching entry in the component's `defineEmits` — see Modal.vue.
+     */
+    onClose?(): void;
+}

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

@@ -0,0 +1,223 @@
+import { PropType } from 'vue';
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    label: {
+        type: PropType<string | false | null>;
+    };
+    error: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Additional help text to display.
+     */
+    helpText: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Renders help text as raw HTML. Use with caution.
+     */
+    helpTextHtml: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Renders a help icon next to the label which links to an external page.
+     */
+    helpLink: {
+        type: PropType<string | false | null>;
+    };
+    placeholder: {
+        type: StringConstructor;
+    };
+    title: {
+        type: () => string | null;
+    };
+    description: {
+        type: () => string | null;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    readonly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, {}, {}, {
+    canFocus(): boolean;
+}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    label: {
+        type: PropType<string | false | null>;
+    };
+    error: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Additional help text to display.
+     */
+    helpText: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Renders help text as raw HTML. Use with caution.
+     */
+    helpTextHtml: {
+        type: PropType<string | false | null>;
+    };
+    /**
+     * Renders a help icon next to the label which links to an external page.
+     */
+    helpLink: {
+        type: PropType<string | false | null>;
+    };
+    placeholder: {
+        type: StringConstructor;
+    };
+    title: {
+        type: () => string | null;
+    };
+    description: {
+        type: () => string | null;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    readonly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    disabled: boolean;
+    loading: boolean;
+    readonly: boolean;
+}, {}, {
+    Icon: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+        icon: {
+            type: StringConstructor;
+        };
+        size: {
+            type: StringConstructor;
+        };
+        contained: {
+            type: BooleanConstructor;
+        };
+        badge: {
+            type: PropType<import('../types').IconBadgeStatusType>;
+        };
+        badgeIcon: {
+            type: StringConstructor;
+        };
+        badgeColor: {
+            type: StringConstructor;
+        };
+    }>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+        icon: {
+            type: StringConstructor;
+        };
+        size: {
+            type: StringConstructor;
+        };
+        contained: {
+            type: BooleanConstructor;
+        };
+        badge: {
+            type: PropType<import('../types').IconBadgeStatusType>;
+        };
+        badgeIcon: {
+            type: StringConstructor;
+        };
+        badgeColor: {
+            type: StringConstructor;
+        };
+    }>> & Readonly<{}>, {
+        contained: boolean;
+    }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+    Labelled: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+        label: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        error: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpText: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpTextHtml: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpLink: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        required: {
+            type: BooleanConstructor;
+            required: false;
+        };
+    }>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+        [key: string]: any;
+    }>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+        label: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        error: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpText: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpTextHtml: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        helpLink: {
+            type: PropType<string | false | null>;
+            required: false;
+        };
+        required: {
+            type: BooleanConstructor;
+            required: false;
+        };
+    }>> & Readonly<{}>, {
+        required: boolean;
+    }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+    Spinner: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+        color: {
+            type: StringConstructor;
+            default: string;
+        };
+        size: {
+            type: StringConstructor;
+            default: string;
+        };
+    }>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+        color: {
+            type: StringConstructor;
+            default: string;
+        };
+        size: {
+            type: StringConstructor;
+            default: string;
+        };
+    }>> & Readonly<{}>, {
+        size: string;
+        color: string;
+    }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/components/NavField/index.d.ts

@@ -0,0 +1 @@
+export { default as NavField } from './NavField.vue';

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

@@ -0,0 +1,47 @@
+import { NavigationProps, NavigationPrimaryItemType } from './types';
+declare var __VLS_6: {
+    theme: import('./types').NavigationThemeType;
+}, __VLS_8: {
+    theme: import('./types').NavigationThemeType;
+}, __VLS_33: {
+    min: boolean;
+};
+type __VLS_Slots = {} & {
+    logo?: (props: typeof __VLS_6) => any;
+} & {
+    logoMin?: (props: typeof __VLS_8) => any;
+} & {
+    footer?: (props: typeof __VLS_33) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<NavigationProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "click-item": (item: NavigationPrimaryItemType, event: MouseEvent) => any;
+    "toggle-min": (v: boolean) => any;
+    "update:location": (id: string) => any;
+    clickLogo: () => any;
+    "open-menu": (item: NavigationPrimaryItemType) => any;
+    back: () => any;
+}, string, import('vue').PublicProps, Readonly<NavigationProps> & Readonly<{
+    "onClick-item"?: ((item: NavigationPrimaryItemType, event: MouseEvent) => any) | undefined;
+    "onToggle-min"?: ((v: boolean) => any) | undefined;
+    "onUpdate:location"?: ((id: string) => any) | undefined;
+    onClickLogo?: (() => any) | undefined;
+    "onOpen-menu"?: ((item: NavigationPrimaryItemType) => any) | undefined;
+    onBack?: (() => any) | undefined;
+}>, {
+    logo: boolean;
+    theme: import('./types').NavigationThemeType;
+    highlight: boolean | string;
+    allowMinimize: boolean;
+    preventDefault: boolean;
+    backLabel: string;
+    minimizePosition: import('./types').NavigationMinimizePositionType;
+    accentStripe: boolean | string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/Navigation/components/Item.vue.d.ts

@@ -0,0 +1,10 @@
+import { NavigationItemProps } from '../types';
+declare const __VLS_export: import('vue').DefineComponent<NavigationItemProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<NavigationItemProps> & Readonly<{}>, {
+    min: boolean;
+    theme: import('..').NavigationThemeType;
+    isSubItem: boolean;
+    hasPrimaryIcons: boolean;
+    highlight: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/Navigation/components/Section.vue.d.ts

@@ -0,0 +1,13 @@
+import { NavigationPrimaryItemType, NavigationSectionProps } from '../types';
+declare const __VLS_export: import('vue').DefineComponent<NavigationSectionProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "click-item": (item: NavigationPrimaryItemType, event: MouseEvent) => any;
+}, string, import('vue').PublicProps, Readonly<NavigationSectionProps> & Readonly<{
+    "onClick-item"?: ((item: NavigationPrimaryItemType, event: MouseEvent) => any) | undefined;
+}>, {
+    min: boolean;
+    theme: import('..').NavigationThemeType;
+    hasPrimaryIcons: boolean;
+    highlight: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/Navigation/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Navigation } from './Navigation.vue';
+export * from './types';

package/dist/components/Navigation/types.d.ts

@@ -0,0 +1,117 @@
+export type NavigationThemeType = 'dark' | 'light';
+/**
+ * A whole menu an item drills down into — the settings-area pattern, where a
+ * click replaces the menu and a Back control returns to the one before.
+ */
+export interface NavigationSubMenuType {
+    /** Heading shown above the sub-menu's sections, under the Back control. */
+    title?: string;
+    sections: NavigationSectionType[];
+}
+/**
+ * Where the min/max control sits when `allowMinimize` is on.
+ *
+ * - `edge` — a floating chevron button hugging the sidebar's right edge, and
+ *   the default: reachable in both states, out of the content's way.
+ * - `top` — inline in the title row, beside the logo or title.
+ * - `bottom` — a full-width row at the very bottom, below the footer.
+ */
+export type NavigationMinimizePositionType = 'edge' | 'top' | 'bottom';
+export interface NavigationProps {
+    theme?: NavigationThemeType;
+    allowMinimize?: boolean;
+    title?: string;
+    location?: string;
+    sections?: NavigationSectionType[];
+    /**
+     * Use to stop navigation of links by automatically calling
+     * `event.preventDefault` on clicks. Useful programmattic navigation while
+     * without needing to remove URLs from item defintiions.
+     */
+    preventDefault?: boolean;
+    /**
+     * Reserves the top of the menu for the `logo` slot — and, when minimized,
+     * the `logoMin` slot, for a square mark that fits the icon rail.
+     */
+    logo?: boolean;
+    /**
+     * Label on the control that leaves a drilled-into sub-menu.
+     *
+     * @default 'Back'
+     */
+    backLabel?: string;
+    /**
+     * Marks the active item with an accent treatment: accent-coloured text and
+     * icon, a soft tinted fill, and a bar on the row's left edge. `true` draws
+     * it in the primary colour; a CSS colour
+     * string (`'#e07a30'`, `'var(--octans-tertiary)'`) draws it in that colour.
+     * Also themeable per-container via `--ui-nav-highlightColor`.
+     *
+     * @default false
+     */
+    highlight?: boolean | string;
+    /**
+     * Where the min/max control sits — see `NavigationMinimizePositionType`.
+     *
+     * @default 'edge'
+     */
+    minimizePosition?: NavigationMinimizePositionType;
+    /**
+     * A full-height brand stripe down the menu's far-left edge, so the
+     * organisation's colour runs the whole window edge.
+     * `true` draws it in the primary colour; a CSS colour string in that colour.
+     * Also themeable per-container via `--ui-nav-accentStripeColor`.
+     *
+     * @default false
+     */
+    accentStripe?: boolean | string;
+}
+export interface NavigationSectionType {
+    id: string;
+    title?: string;
+    /**
+     * An Iconify name shown before the section title. Also what represents the
+     * section while the menu is minimized, so sections stay tellable-apart on
+     * the icon rail.
+     */
+    icon?: string;
+    action?: {
+        icon: string;
+    };
+    items?: NavigationPrimaryItemType[];
+}
+export interface NavigationSecondaryItemType {
+    id: string;
+    label: string;
+    url?: string;
+    badge?: string;
+    active?: boolean;
+    onAction?: (item: NavigationSecondaryItemType) => void;
+}
+export interface NavigationPrimaryItemType extends NavigationSecondaryItemType {
+    icon?: string;
+    items?: NavigationSecondaryItemType[];
+    /**
+     * A whole menu this item drills down into, replacing the current one with a
+     * Back control at the top. Clicking the item opens the menu instead of
+     * navigating — `url` and `onAction` are ignored when this is set.
+     */
+    subMenu?: NavigationSubMenuType;
+}
+export interface NavigationSectionProps {
+    theme?: NavigationThemeType;
+    section: NavigationSectionType;
+    location?: string;
+    hasPrimaryIcons?: boolean;
+    min?: boolean;
+    highlight?: boolean;
+}
+export interface NavigationItemProps {
+    theme?: NavigationThemeType;
+    item: NavigationPrimaryItemType;
+    isSubItem?: boolean;
+    location?: string;
+    hasPrimaryIcons?: boolean;
+    min?: boolean;
+    highlight?: boolean;
+}