@octans/ui 1.0.0 → 1.3.0

package/README.md

@@ -7,8 +7,9 @@ shell components.
 
 <br clear="left" />
 
-[octans.dev](https://octans.dev) — live Storybook docs ·
-[github.com/tarwin/octans-ui](https://github.com/tarwin/octans-ui) ·
+[octans.dev](https://octans.dev) ·
+[Quick start](https://octans.dev/storybook/?path=/docs/documentation-quick-start--docs) ·
+[Kitchen sink](https://octans.dev/storybook/?path=/story/documentation-kitchen-sink--all-components) ·
 [Issues](https://github.com/tarwin/octans-ui/issues)
 
 ## Install
@@ -21,6 +22,24 @@ pnpm add @octans/ui
 if you use the components that render router links (`MaybeRouterLink`,
 `UnstyledLink`, and anything that accepts a `to` prop).
 
+### A note on the `vue-demi` build warning
+
+pnpm may report an ignored build script on install:
+
+```
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: vue-demi
+```
+
+This is safe to ignore. `vue-demi` arrives transitively via
+`reka-ui` → `@floating-ui/vue`, which still supports Vue 2 alongside Vue 3. Its
+postinstall only switches the package entry point to match the detected Vue
+version, and the shipped default is already the Vue 3 build — so skipping it
+changes nothing on Vue 3. Run `pnpm approve-builds` if you would rather the
+warning went away.
+
+It will disappear on its own once `reka-ui` moves to `@floating-ui/vue` v2,
+which dropped `vue-demi`.
+
 ## Usage
 
 ```ts
@@ -33,6 +52,20 @@ import App from './App.vue'
 createApp(App).use(Octans).mount('#app')
 ```
 
+### `reset.css`
+
+`style.css` resets nothing outside `.UIElement`, so the library can be dropped
+into a page it doesn't own without moving anything on it. If Octans is the
+whole UI, add the opt-in page reset as well — otherwise the markup your app
+renders itself keeps the browser's defaults: serif text, the 8px body margin,
+`content-box` sizing, and a body with no height that grows into a second
+scrollbar.
+
+```ts
+import '@octans/ui/style.css'
+import '@octans/ui/reset.css' // only when Octans owns the page
+```
+
 Components can also be imported individually without installing the plugin:
 
 ```vue
@@ -173,6 +206,7 @@ pnpm dev            # Storybook on :6006
 | Script            | Does                                             |
 | ----------------- | ------------------------------------------------ |
 | `pnpm dev`        | Storybook dev server                             |
+| `pnpm build-site` | Landing page + Storybook into `site-dist/`       |
 | `pnpm build-lib`  | Build the ES + UMD bundles and type declarations |
 | `pnpm type-check` | `vue-tsc --noEmit`                               |
 | `pnpm lint`       | ESLint                                           |
@@ -221,6 +255,15 @@ export interface SelectOptionType {
 }
 ```
 
+## Acknowledgements
+
+- [Bryce Farrell](https://github.com/brycefarrell) — especially for ideas on how
+  to structure internal APIs to make them easy to use.
+- [Ramunė Rastonis](https://www.instagram.com/ramunerastonis/) — for design
+  consulting.
+
+Any shortcomings are my own fault.
+
 ## License
 
 [MIT](./LICENSE)

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

@@ -1,4 +1,5 @@
-import { PopperPlacementType } from '../Popper';
+import { VNodeChild } from 'vue';
+import { PopoverPlacementType } from '../Popover';
 import { ActionTooltipPositionType } from '../types';
 export interface ActionListProps {
     /**
@@ -9,10 +10,10 @@ export interface ActionListProps {
      * Groups of actions to render.
      */
     sections?: ActionListSectionType[];
-    placement?: PopperPlacementType;
+    placement?: PopoverPlacementType;
     disabled?: boolean;
     /**
-     * Custom z-index for the popper.
+     * Custom z-index for the popover.
      */
     zIndex?: number;
     /**
@@ -32,6 +33,13 @@ export interface ActionListItemType {
      * Secondary text shown beneath the label.
      */
     helpText?: string;
+    /**
+     * Renders the row's body in place of `label` (and `helpText`), for items
+     * that are more than text — a label with a Badge beside it, say. `label` is
+     * still required: it stays the item's accessible, sortable name, and is what
+     * a consumer reading the items back gets.
+     */
+    content?: () => VNodeChild;
     disabled?: boolean;
     url?: string;
     external?: boolean;
@@ -64,7 +72,7 @@ declare const __VLS_base: import('vue').DefineComponent<ActionListProps, {}, {},
     onHide?: (() => any) | undefined;
     onClose?: (() => any) | undefined;
 }>, {
-    placement: PopperPlacementType;
+    placement: PopoverPlacementType;
     items: ActionListItemType[];
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/components/ActionList/ActionListButton.vue.d.ts

@@ -1,4 +1,4 @@
-import { PropType, VNode } from 'vue';
+import { PropType, VNode, VNodeChild } from 'vue';
 declare const _default: typeof __VLS_export;
 export default _default;
 declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
@@ -8,6 +8,12 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
     helpText: {
         type: StringConstructor;
     };
+    /**
+     * Renders the row's body in place of `label` and `helpText`.
+     */
+    content: {
+        type: PropType<() => VNodeChild>;
+    };
     disabled: {
         type: BooleanConstructor;
         default: boolean;
@@ -47,6 +53,12 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
     helpText: {
         type: StringConstructor;
     };
+    /**
+     * Renders the row's body in place of `label` and `helpText`.
+     */
+    content: {
+        type: PropType<() => VNodeChild>;
+    };
     disabled: {
         type: BooleanConstructor;
         default: boolean;

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

@@ -1,13 +1,13 @@
 import { AppFrameProps } from './types';
-declare var __VLS_8: {}, __VLS_10: {}, __VLS_38: {}, __VLS_40: {};
+declare var __VLS_8: {}, __VLS_10: {}, __VLS_43: {}, __VLS_45: {};
 type __VLS_Slots = {} & {
     sidebar?: (props: typeof __VLS_8) => any;
 } & {
     topbar?: (props: typeof __VLS_10) => any;
 } & {
-    default?: (props: typeof __VLS_38) => any;
+    default?: (props: typeof __VLS_43) => any;
 } & {
-    footer?: (props: typeof __VLS_40) => any;
+    footer?: (props: typeof __VLS_45) => any;
 };
 declare const __VLS_base: import('vue').DefineComponent<AppFrameProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<AppFrameProps> & Readonly<{}>, {
     loading: boolean;

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

@@ -1,4 +1,4 @@
-import { PopperPlacementType } from '../Popper';
+import { PopoverPlacementType } from '../Popover';
 import { PropType } from 'vue';
 import { BadgeProgressType, BadgeSizeType, BadgeStatusType } from '../types';
 /**
@@ -53,7 +53,7 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
      * Placement of the tooltip if rendered
      */
     tooltipPosition: {
-        type: PropType<PopperPlacementType>;
+        type: PropType<PopoverPlacementType>;
     };
     /**
      * An optional radius value for the badge edges
@@ -110,7 +110,7 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
      * Placement of the tooltip if rendered
      */
     tooltipPosition: {
-        type: PropType<PopperPlacementType>;
+        type: PropType<PopoverPlacementType>;
     };
     /**
      * An optional radius value for the badge edges

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

@@ -170,6 +170,14 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             type: BooleanConstructor;
             default: boolean;
         };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        pressed: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
     }>, () => 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<{
@@ -225,15 +233,25 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             type: BooleanConstructor;
             default: boolean;
         };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        pressed: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
     }>> & Readonly<{}>, {
         disabled: boolean;
         size: string;
         type: import('../types').ActionTypeType;
         destructive: boolean;
+        loading: boolean;
         tooltipPosition: import('../types').ActionTooltipPositionType;
         external: boolean;
         dropdown: boolean;
         fullWidth: boolean;
         invert: boolean;
+        pressed: boolean;
     }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
 }, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

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

@@ -138,6 +138,38 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * Swaps the label for a spinner while an action is in flight, and stops
+     * the button acting.
+     *
+     * The label stays in the layout and is only made invisible, so the button
+     * keeps its width — a toolbar that reflows the instant something is
+     * clicked is worse than a slow one.
+     *
+     * It sets `aria-disabled`, NOT `disabled`. A real `disabled` attribute on
+     * a focused button drops focus to `<body>`, which is precisely the moment
+     * a keyboard user is waiting for something to happen.
+     */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Marks a toggle button as on. The resting surface takes whatever
+     * treatment the type already uses for `:active`, and the button announces
+     * `aria-pressed`.
+     *
+     * `undefined` by default rather than `false`, so the attribute appears
+     * only on a button that IS a toggle: `:pressed="false"` announces a
+     * toggle that is off, while omitting it announces nothing at all.
+     *
+     * For a set of mutually exclusive options reach for `SegmentedControl`
+     * instead — this is for a toggle that stands on its own.
+     */
+    pressed: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }>, () => VNode<import('vue').RendererNode, import('vue').RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
@@ -271,14 +303,48 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * Swaps the label for a spinner while an action is in flight, and stops
+     * the button acting.
+     *
+     * The label stays in the layout and is only made invisible, so the button
+     * keeps its width — a toolbar that reflows the instant something is
+     * clicked is worse than a slow one.
+     *
+     * It sets `aria-disabled`, NOT `disabled`. A real `disabled` attribute on
+     * a focused button drops focus to `<body>`, which is precisely the moment
+     * a keyboard user is waiting for something to happen.
+     */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Marks a toggle button as on. The resting surface takes whatever
+     * treatment the type already uses for `:active`, and the button announces
+     * `aria-pressed`.
+     *
+     * `undefined` by default rather than `false`, so the attribute appears
+     * only on a button that IS a toggle: `:pressed="false"` announces a
+     * toggle that is off, while omitting it announces nothing at all.
+     *
+     * For a set of mutually exclusive options reach for `SegmentedControl`
+     * instead — this is for a toggle that stands on its own.
+     */
+    pressed: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
     disabled: boolean;
     size: string;
     type: ActionTypeType;
     destructive: boolean;
+    loading: boolean;
     tooltipPosition: ActionTooltipPositionType;
     external: boolean;
     dropdown: boolean;
     fullWidth: boolean;
     invert: boolean;
+    pressed: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

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

@@ -6,6 +6,23 @@ export interface CalendarCellType {
     isCurrent?: boolean;
     isOtherPeriod?: boolean;
     isDisabled?: boolean;
+    /** Markers falling on this cell, in the order they were given. */
+    markers?: CalendarMarkerType[];
+}
+/**
+ * A dot drawn under a day, for saying "something happens here" without
+ * selecting it — deadlines, bookings, days with data.
+ */
+export interface CalendarMarkerType {
+    /**
+     * The day to mark. Anything DayJS can parse, including a `Date` or another
+     * `Dayjs`; only the day part is used.
+     */
+    date: string | number | Date | Dayjs;
+    /** Any CSS colour. Defaults to the theme's primary. */
+    color?: string;
+    /** Native tooltip on the day. Several markers on a day join with a comma. */
+    tooltip?: string;
 }
 export interface CalendarProps {
     /**
@@ -36,4 +53,39 @@ export interface CalendarProps {
      * Restricts the maximum time that can be selected.
      */
     maxTime?: string;
+    /**
+     * The earliest selectable date, inclusive. Anything DayJS can parse.
+     *
+     * `disableDate` can express this too, but a range is the common case and
+     * writing a predicate for it every time is the wrong amount of work. Both
+     * apply when both are given.
+     */
+    minDate?: string | number | Date | Dayjs;
+    /**
+     * The latest selectable date, inclusive.
+     */
+    maxDate?: string | number | Date | Dayjs;
+    /**
+     * The day the week starts on, `0` Sunday through `6` Saturday.
+     *
+     * Normally you should NOT set this: the week start comes from the active
+     * locale, so `setLocale('fr')` already moves it to Monday. This is the
+     * per-instance override for a calendar that has to disagree with the
+     * viewer's locale — a roster in a fixed business week, say.
+     */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Days to mark with a dot.
+     */
+    markers?: CalendarMarkerType[];
+    /**
+     * The time zone that decides what "today" is, as an IANA name
+     * (`'America/Los_Angeles'`). Defaults to the library-wide display time zone
+     * — see `setTimezone` — and, failing that, the viewer's own clock.
+     *
+     * This moves the highlighted day and the day an empty picker opens on. It
+     * does NOT convert `modelValue`: the model is a wall clock in
+     * `modelFormat`, parsed and formatted without a zone, and it stays that way.
+     */
+    timezone?: string;
 }

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

@@ -2,8 +2,8 @@ import { CalendarHeatmapProps, CalendarHeatmapSeries } from './types';
 declare const __VLS_export: import('vue').DefineComponent<CalendarHeatmapProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<CalendarHeatmapProps> & Readonly<{}>, {
     data: import('./types').CalendarHeatmapDataPoint[];
     tooltip: boolean;
-    series: CalendarHeatmapSeries[];
     weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    series: CalendarHeatmapSeries[];
     emptyColor: string;
     cellSize: number;
     cellGap: number;

package/dist/components/Card/CardSection.vue.d.ts

@@ -84,6 +84,6 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
     };
 }>> & Readonly<{}>, {
     subdued: boolean;
-    collapseActions: boolean;
     padded: boolean;
+    collapseActions: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

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

@@ -7,7 +7,7 @@ declare const __VLS_export: import('vue').DefineComponent<ColorSelectorProps, {}
     "onUpdate:modelValue"?: ((value: string | Gradient) => any) | undefined;
     "onUpdate:swatches"?: ((value: string[]) => any) | undefined;
 }>, {
-    placement: import('../Popper').PopperPlacementType;
+    placement: import('../Popover').PopoverPlacementType;
     disabled: boolean;
     trigger: import('./types').ColorSelectorTriggerType;
     mode: import('./types').ColorSelectorMode;

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

@@ -1,5 +1,5 @@
 import { ColorPickerProps } from '../ColorPicker';
-import { PopperPlacementType } from '../Popper';
+import { PopoverPlacementType } from '../Popover';
 import { Gradient, GradientType } from '../../utils/gradient';
 /**
  * What the field is allowed to hold.
@@ -59,7 +59,7 @@ export interface ColorSelectorProps extends Omit<ColorPickerProps, 'modelValue'>
     /**
      * Where the picker opens relative to the trigger.
      */
-    placement?: PopperPlacementType;
+    placement?: PopoverPlacementType;
     /**
      * What you click to open the picker. `swatch` strips the control back to the
      * colour itself; `input` lets the value be typed.

package/dist/components/DataTable/BulkActions.vue.d.ts

@@ -45,7 +45,7 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             hide: () => any;
             close: () => any;
         }, import('vue').PublicProps, {
-            placement: import('../Popper').PopperPlacementType;
+            placement: import('../Popover').PopoverPlacementType;
             items: import('../ActionList').ActionListItemType[];
         }, false, {}, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, {}, any, import('vue').ComponentProvideOptions, {
             P: {};
@@ -59,7 +59,7 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             onHide?: (() => any) | undefined;
             onClose?: (() => any) | undefined;
         }>, {}, {}, {}, {}, {
-            placement: import('../Popper').PopperPlacementType;
+            placement: import('../Popover').PopoverPlacementType;
             items: import('../ActionList').ActionListItemType[];
         }>;
         __isFragment?: never;
@@ -74,7 +74,7 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
         hide: () => any;
         close: () => any;
     }, string, {
-        placement: import('../Popper').PopperPlacementType;
+        placement: import('../Popover').PopoverPlacementType;
         items: import('../ActionList').ActionListItemType[];
     }, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps & (new () => {
         $slots: {
@@ -134,6 +134,14 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             type: BooleanConstructor;
             default: boolean;
         };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        pressed: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
     }>, () => 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<{
@@ -189,16 +197,26 @@ declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractP
             type: BooleanConstructor;
             default: boolean;
         };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        pressed: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
     }>> & Readonly<{}>, {
         disabled: boolean;
         size: string;
         type: import('../types').ActionTypeType;
         destructive: boolean;
+        loading: boolean;
         tooltipPosition: import('../types').ActionTooltipPositionType;
         external: boolean;
         dropdown: boolean;
         fullWidth: boolean;
         invert: boolean;
+        pressed: boolean;
     }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
     ButtonGroup: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
         segmented: {

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

@@ -1,4 +1,5 @@
 import { Dayjs } from 'dayjs';
+import { CalendarMarkerType } from '../Calendar';
 export interface DatePickerProps {
     label?: string | false;
     error?: string | false | null;
@@ -54,4 +55,36 @@ export interface DatePickerProps {
      * If set to `false` will not automatically display the picker.
      */
     autoOpen?: boolean;
+    /**
+     * The earliest selectable date, inclusive. Anything DayJS can parse.
+     */
+    minDate?: string | number | Date | Dayjs;
+    /**
+     * The latest selectable date, inclusive.
+     */
+    maxDate?: string | number | Date | Dayjs;
+    /**
+     * The day the week starts on, `0` Sunday through `6` Saturday. Comes from
+     * the active locale unless set — see `Calendar`.
+     */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Days to mark with a dot in the calendar.
+     */
+    markers?: CalendarMarkerType[];
+    /**
+     * IANA time zone deciding what "today" is. Defaults to the library-wide
+     * display zone — see `setTimezone`. It does not convert `modelValue`.
+     */
+    timezone?: string;
+    /**
+     * Marks the field as required: an asterisk after the label, and
+     * `aria-required` on the control.
+     *
+     * Announced, not enforced — it deliberately does NOT set the native
+     * `required` attribute, so the browser's own validation bubble stays out of
+     * the way of whatever the app does about errors. Use `error` to show a
+     * failure.
+     */
+    required?: boolean;
 }