@webx-ui/module-admin 0.4.2 → 0.5.0

package/README.md

@@ -76,6 +76,38 @@ behind it still has labels.
 That is what an editing screen builds its tabs from, and it has nothing to do with the language
 of the interface around them.
 
+## Dates
+
+One way to say when something happened, for every screen in the panel.
+
+```vue
+<script setup lang="ts">
+import { useDates, WxDate } from '@webx-ui/module-admin'
+
+const dates = useDates() // dates.short(row.updated_at), dates.exact(…), dates.iso(…)
+</script>
+
+<template>
+  <wx-date :value="row.last_login_at" />
+</template>
+```
+
+| When         | What it says            |
+| ------------ | ----------------------- |
+| today        | `today at 08:10`        |
+| yesterday    | `yesterday at 14:03`    |
+| this year    | `16 September at 14:03` |
+| earlier      | `16 September 2025`     |
+| never at all | `never`                 |
+
+Twenty-four hours, no seconds; `WxDate` keeps the exact moment in a tip and in `<time
+datetime>`, so a column is read at a glance and an argument about the exact second still has an
+answer. The month names and the order of the parts come from `Intl` in the **panel's** language,
+not the browser's; `today` is counted in the reader's own day, which is why a server sending UTC
+does not turn somebody's morning into yesterday.
+
+Nothing here touches ordering: a sortable column sorts on the value the server sent.
+
 ## Talking to the backend
 
 ```ts
@@ -111,6 +143,7 @@ everything, the same rule the server applies.
 | `useAdmin`                | The context: `http`, `state`, `nav`, `can`     |
 | `createHttp`, `HttpError` | The client, usable on its own                  |
 | `AdminShell`, `AdminNav`  | The layout, for a panel that assembles its own |
+| `useDates`, `WxDate`      | When something happened, in words              |
 
 Styles come with `@webx-ui/core`; this package adds a little of its own:
 

package/dist/AdminShell.d.ts

@@ -2,13 +2,16 @@ declare function __VLS_template(): {
     attrs: Partial<{}>;
     slots: {
         brand?(_: {}): any;
+        brand?(_: {}): any;
+        user?(_: {}): any;
+        user?(_: {}): any;
         user?(_: {}): any;
         nav?(_: {
             collapsed: boolean;
         }): any;
         nav?(_: {
             collapsed: boolean;
-            onSelect: () => void;
+            select: () => void;
         }): any;
     };
     refs: {

package/dist/DateText.d.ts

@@ -0,0 +1,23 @@
+import { TextSize, TextTone } from '@webx-ui/core';
+import { DateLike } from './dates';
+/**
+ * When something happened, the way the whole panel says it (§21).
+ *
+ * The short line is what the column holds — "today at 08:10" is read at a glance where
+ * "17.09.2026, 08:10" is read twice. The second down to the second stays in the tip, because
+ * the question "when exactly" is asked rarely and answered badly by a column.
+ *
+ * Its own tip rather than `title`: the native one waits a second, cannot be styled, and is
+ * invisible to anybody who is not holding a mouse (§16).
+ */
+type __VLS_Props = {
+    /** What the server sent. `null` is a date that never happened, not a missing one. */
+    value: DateLike;
+    size?: TextSize;
+    tone?: TextTone;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: TextSize;
+    tone: TextTone;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/ListScreen.d.ts

@@ -0,0 +1,80 @@
+import { CardPadding, TabItem, TabValue } from '@webx-ui/core';
+/**
+ * The frame every list of the panel is drawn in.
+ *
+ * One shape for all of them, because five sections that each answered "where does the heading
+ * go" on their own gave five answers — a heading inside the card on `Administrators`, two
+ * headings on `SEO`, a search outside the card on `Blocks`, no heading at all on `Files`. A
+ * reader who learns one list should already know the next.
+ *
+ * The shape is: the section's name on the left of its own line, the one action the section
+ * exists for on the right of it, the views of the list as tabs under that, and a card holding
+ * nothing but the rows. The card has no heading of its own — the tab says which view it is,
+ * and the line above says which section (§19). The search stays inside the table, where it is
+ * a property of the rows rather than of the screen (§10).
+ *
+ * What it deliberately does not do is fetch, filter or page. It is a frame; the section still
+ * owns its data, and the tabs only say which view is open.
+ */
+type __VLS_Props = {
+    /** The section's name. The one heading on the screen. */
+    title?: string;
+    /**
+     * The views of the same list — "All / Drafts / Published", "Rules / Redirects". Not a
+     * navigation between screens: everything under them is the same table.
+     */
+    views?: TabItem[];
+    /** Wrap the rows in a card. Off for a section that brings its own. */
+    card?: boolean;
+    /** Padding of that card; `WxCard`'s own default when not given. */
+    padding?: CardPadding;
+    /** The screen is as tall as the column it is drawn in — a file manager, a board. */
+    fill?: boolean;
+    /** Container width below which the views fold into one switch. */
+    collapseBelow?: number;
+};
+type __VLS_PublicProps = {
+    'view'?: TabValue | undefined;
+} & __VLS_Props;
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        /** The rows: a table, a grid of cards, a manager. */
+        default?: () => unknown;
+        /**
+         * The screen's buttons, beside the heading. One of them — the reason the section exists —
+         * is a filled primary button with a word on it; everything else is outlined or an icon.
+         */
+        actions?: () => unknown;
+    }> & {
+        /** The rows: a table, a grid of cards, a manager. */
+        default?: () => unknown;
+        /**
+         * The screen's buttons, beside the heading. One of them — the reason the section exists —
+         * is a filled primary button with a word on it; everything else is outlined or an icon.
+         */
+        actions?: () => unknown;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:view": (value: TabValue | undefined) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:view"?: ((value: TabValue | undefined) => any) | undefined;
+}>, {
+    title: string;
+    views: TabItem[];
+    card: boolean;
+    padding: CardPadding;
+    fill: boolean;
+    collapseBelow: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/RowMenu.d.ts

@@ -0,0 +1,28 @@
+import { ActionSize } from '@webx-ui/core';
+import { RowAction } from './types';
+/**
+ * What one record offers, in every list of the panel: a `···` at the end of the row.
+ *
+ * Always a menu, even for a single action. The panel used to have three answers to this —
+ * a menu on `Pages`, a bare red bin on `SEO`, a toolbar over the selection in the library —
+ * and the cost of that is not the extra click, it is that nobody knows where to look. A
+ * menu also has room for the word: an unlabelled icon says what it does only to whoever has
+ * already learned it (§20).
+ *
+ * Two rules it keeps for every list rather than leaving to each one. The destructive action
+ * goes last, behind a rule, in red — it is never the thing the reader meant to hit. And what
+ * somebody may not do is left out, not shown greyed: a menu is a list of what is possible,
+ * and a row of dead entries teaches nothing.
+ */
+type __VLS_Props = {
+    /** What may be done, in the order it should read. */
+    actions: RowAction[];
+    /** Accessible name of the menu — the record it belongs to. */
+    label?: string;
+    size?: ActionSize;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: ActionSize;
+    label: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/dates.d.ts

@@ -0,0 +1,40 @@
+import { I18n } from './i18n';
+/** A moment as it arrives: ISO-8601 from the server, a timestamp, a `Date`, or nothing. */
+export type DateLike = string | number | Date | null | undefined;
+export interface Dates {
+    /**
+     * The line a reader sees: "today at 08:10", "yesterday at 14:03", "16 September at 14:03",
+     * "16 September 2025", "never".
+     */
+    short(value: DateLike): string;
+    /**
+     * Everything there is, down to the second — what the tip holds when the short line is not
+     * precise enough to settle an argument. Empty when there is no date.
+     */
+    exact(value: DateLike): string;
+    /** The machine value for `<time datetime>`. Empty when there is no date. */
+    iso(value: DateLike): string;
+}
+/**
+ * How the panel says when something happened — one answer for every screen in it.
+ *
+ * Three rules it would be easy to lose, and each of them was a bug before this existed:
+ *
+ * - the language is the panel's, not the browser's. `toLocaleString()` with no locale reads
+ *   the browser's settings, so a panel drawn in Russian was dating its rows in American
+ *   order. The locale comes from `i18n`, which is what the administrator chose.
+ * - "today" is counted in the administrator's own day. The server sends UTC; comparing UTC
+ *   dates would write "yesterday" over anything that happened before 03:00 in Moscow. The
+ *   comparison is made on local calendar days, which is what the reader means by today.
+ * - the shown string is never what sorts. Nothing here touches ordering: a column sorts on
+ *   the value the server sent, or "yesterday" lands between the sixteenth and the seventeenth.
+ */
+export declare function createDates(i18n: I18n): Dates;
+/**
+ * The formatter, inside a panel or outside one.
+ *
+ * Outside a panel — a screen mounted by hand, a story, a test — there is no dictionary to read,
+ * so one is made once with this package's own English in it. A component that may be used
+ * either way should not have to know which it is.
+ */
+export declare function useDates(): Dates;

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+import { Translate } from './i18n';
+/**
+ * What to say out loud when a request came back a failure.
+ *
+ * The panel used to print whatever the server put in `message`, which is fine right up until
+ * the server has not written it. `No query results for model [WebxUi\Pages\Models\Page] 8` is
+ * Laravel talking to a developer — a namespace, in English, in a panel translated into ten
+ * languages — and it reached an editor who had only clicked a row in the bin (§13.3).
+ *
+ * So the rule is which status the panel trusts to speak for itself, not which words look
+ * technical. A 422 is ours: every refusal that reaches one is written by a module to be read,
+ * through `trans()`, and the validator's lines are translated by Laravel. Everything else —
+ * 404, 403, 500, a server that never answered — carries text nobody wrote for this reader, and
+ * the panel says it in its own words instead.
+ */
+export declare function errorText(error: unknown, t: Translate, fallback?: string): string;
+/**
+ * The same thing for a component, bound to the panel's own dictionary.
+ *
+ * A module calls this rather than its own `t`, because these lines belong to the panel: every
+ * section fails in the same handful of ways, and translating "you are not allowed to do that"
+ * once per module is how nine of them end up saying it differently.
+ */
+export declare function useErrorText(): (error: unknown, fallback?: string) => string;

package/dist/index.d.ts

@@ -2,8 +2,14 @@ export { createAdmin, type Admin, type AdminPlugin, type CreateAdminOptions } fr
 export { createAdminContext, provideAdmin, useAdmin, adminKey, type AdminContext, type AdminState, } from './admin';
 export { createI18n, provideI18n, useI18n, useTranslate, i18nKey, type Dictionary, type I18n, type I18nState, type LocaleDescriptor, type Messages, type Translate, } from './i18n';
 export { adminMessages } from './messages';
+export { createDates, useDates, type DateLike, type Dates } from './dates';
+export { errorText, useErrorText } from './errors';
 export { createHttp, readCookie, HttpError, type Http, type HttpOptions, type RequestOptions, } from './http';
-export type { AdminModule, AdminStatus, AdminUser, Manifest, ManifestModule, NavEntry, } from './types';
+export { adminTypes } from './screenTypes';
+export type { AdminModule, AdminStatus, AdminUser, Manifest, ManifestModule, NavEntry, RowAction, } from './types';
 export { default as AdminShell } from './AdminShell';
 export { default as AdminNav } from './AdminNav';
 export { default as WxScreen } from './Screen';
+export { default as WxListScreen } from './ListScreen';
+export { default as WxRowMenu } from './RowMenu';
+export { default as WxDate } from './DateText';