@knkcs/mediahub-ui 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,62 @@
+# @knkcs/mediahub-ui
+
+Mediahub's reusable UI, published as a versioned npm package so that every host renders the same
+media surfaces instead of re-implementing them.
+
+Two hosts consume it today: knkCMS core, which embeds it as a build-time dependency, and mediahub's
+own standalone app, which consumes it through the workspace.
+
+## Screens, not routes
+
+A screen takes **typed paths** and emits **callbacks**; the host owns routing and draws the page
+frame. No screen builds a URL, and no host builds UI a screen already owns.
+
+That contract is the point of the package. When a host re-implements a surface instead of composing
+it, the two copies diverge and bugs are fixed in one of them — see
+[knkCS/mediahub#138](https://github.com/knkCS/mediahub/issues/138), which consolidated the asset-type
+screens after four such bugs, and
+[mediahub ADR 0008](../../docs/adr/0008-narrowing-composes-folder-collection-and-tag.md), which
+removed a host-built browse switcher for the same reason.
+
+## What it exports
+
+| Surface | What it is |
+|---|---|
+| `AssetLibrary` | The media browser: folder tree, filters, upload, and the context rail carrying Tags and Collections |
+| `AssetDetail` | One asset, its versions and its metadata |
+| `AssetPicker`, `CollectionPicker` | Embeddable pickers for a host's own forms |
+| `AssetTypeIndex`, `AssetTypeCreate`, `AssetTypeDetail` | Asset-type administration, including the AI-processes tab |
+| `CollectionIndex` | The Collections the user can see, marking the Restricted ones. Listing is not gated by authority — per [ADR 0001](../../docs/adr/0001-grant-authority-owner-or-workspace-admin.md) seeing a Collection and managing it are separate privileges |
+| `CollectionCreate` | Create a Collection from a name, slug and description. **Static only** — a smart Collection's `rules` are stored and never evaluated, so no type selector and no rules editor appear ([#173](https://github.com/knkCS/mediahub/issues/173)) |
+| `CollectionDetail` | One Collection's identity — name, description, delete — **and its access control**: the Restricted toggle (with the leak-guard refusal naming what it would expose) and the roster, offered only where the can-manage probe says the reader is an authority ([ADR 0001](../../docs/adr/0001-grant-authority-owner-or-workspace-admin.md): owner-on-the-Collection or admin-on-its-workspace, and grantees never see the roster). Not Curation: adding and removing assets happens in the library, where the assets are |
+| `MediahubProvider` | The provider a host mounts once, holding the clients and query client |
+| Clients | `createConnectMediahubClients` adapts per-service Connect clients into the domain clients the screens' hooks read, and owns the mapping — a host supplies transport only |
+| Hooks and stores | The queries and mutations behind the screens, for a host composing its own view |
+
+Everything lands at the package root (`.`). A second entry point, `./testing`, ships a stub client
+and fixtures so a host can test its own composition without a server.
+
+## Narrowing composes
+
+Folder, Collection and Tag narrow the library **together** — one folder, many collections, many tags.
+They are not alternative modes, and a UI that makes them mutually exclusive cannot express a question
+the data model permits. `AssetLibrary` accounts for what is applied with a row of dismissible filter
+chips. See ADR 0008 and the `Narrowing` entry in [`CONTEXT.md`](../../CONTEXT.md).
+
+## Layout comes from anker
+
+Screens use anker's templates and primitives — `IndexPageTemplate`, `DetailPageTemplate`,
+`SubNavLayout`, `ContextRail` — and report their frame through anker's host contract. anker's own
+guidance is explicit: if a template does not fit, file an issue rather than hand-rolling a layout.
+
+## Peers
+
+Every non-trivial dependency is a **peer** the host supplies once, so a host and the package can
+never load two copies of React, the query client or anker. The Rollup external list is derived from
+`peerDependencies`, so declaring a peer is the whole change.
+
+## Releases
+
+Versioned with release-please from conventional commits, and published to npm by CI. A commit whose
+subject loses its `feat:`/`fix:` prefix — which a squash merge can do — produces no release at all,
+silently ([knkCS/mediahub#185](https://github.com/knkCS/mediahub/issues/185)).

package/dist/index.d.ts

@@ -13,6 +13,46 @@ import { UseMutateFunction } from '@tanstack/react-query';
 import { UseMutationResult } from '@tanstack/react-query';
 import { UseQueryResult } from '@tanstack/react-query';
 
+/** One narrowing currently applied to the library. */
+export declare interface ActiveFilterChip {
+    /** Stable identity for the row — never rendered. */
+    id: string;
+    /**
+     * What the chip says, already translated and already resolved to a name.
+     * A chip never carries a raw id: the caller resolves Folder, Collection
+     * and Tag through the data the panels load, and falls back to the kind's
+     * own word when a row cannot be resolved.
+     */
+    label: string;
+    /** Removes exactly this filter, leaving the others applied. */
+    onRemove: () => void;
+}
+
+/**
+ * The library's account of what is narrowing it (ADR 0008).
+ *
+ * Presentation only: it owns no filter state and resolves no names — it
+ * renders the chips it is handed and reports the dismissals, so the caller's
+ * single filter state stays the one source the panels also write.
+ *
+ * With nothing applied it renders `null` rather than an empty band, so the
+ * row costs no vertical space until there is something to account for.
+ *
+ * Each chip is anker's `Toolbar.FilterChip`, a native button — reachable by
+ * Tab and activated by Enter or Space with no key handling of our own.
+ */
+export declare const ActiveFilterChips: React.FC<ActiveFilterChipsProps>;
+
+export declare interface ActiveFilterChipsProps {
+    chips: ActiveFilterChip[];
+    onClearAll: () => void;
+    /** Names the group for assistive technology, e.g. "Active filters". */
+    groupLabel: string;
+    /** Said before each chip's label, so the button announces what it does. */
+    removeLabel: string;
+    clearAllLabel: string;
+}
+
 export declare interface AddVersionVars {
     assetId: string;
     file: File;
@@ -564,6 +604,146 @@ export declare interface CollectionClient {
     setRestricted(id: string, restricted: boolean): Promise<CollectionInfo>;
 }
 
+/**
+ * Create a Collection. The package owns the screen; both hosts compose it and
+ * keep their routing to themselves (#176, parent #174).
+ *
+ * **Static Collections only.** There is deliberately no Smart/Static selector
+ * and no `rules` editor, though the standalone app's form dialog offered both.
+ * A smart Collection's `rules` are validated as JSON, stored and returned —
+ * and never evaluated anywhere; membership resolves exclusively through
+ * explicit edges. The control would therefore do nothing at all, and this
+ * project does not ship a known-inert control into a second host
+ * (knkCS/mediahub#173). Every Collection created here is `static` with empty
+ * rules.
+ *
+ * The slug follows the name until it is edited by hand and then stops, and the
+ * server's rule (lowercase alphanumeric with hyphens, at least two characters)
+ * is both stated on the form and enforced before submit — without both, a name
+ * like `Bild Anhang` produced a bare 400 (knkcms/core#861).
+ */
+export declare function CollectionCreate({ collectionsPath, onCreated, onCancel, }: CollectionCreateProps): default_2.JSX.Element;
+
+export declare namespace CollectionCreate {
+    var displayName: string;
+}
+
+export declare interface CollectionCreateProps {
+    /**
+     * The host's Collection index path — the breadcrumb's target. A path, not a
+     * route: the screen never navigates, it only says where the list it belongs
+     * to lives (core's `docs/service-integration.md`; spec #174).
+     */
+    collectionsPath: string;
+    /**
+     * The Collection was created; the host receives its id and decides where to
+     * go. Id only, like `CollectionIndex`'s `onOpen` — the host needs it to
+     * build a detail URL, and nothing here knows what that URL looks like.
+     */
+    onCreated?: (collectionId: string) => void;
+    /** Called when the administrator abandons the form. */
+    onCancel?: () => void;
+}
+
+/**
+ * The packaged collection detail screen: view one Collection, correct its name
+ * and description, delete it behind a confirmation, and — for an authority —
+ * decide who may see it.
+ *
+ * **Authority, per ADR 0001**, is owner-on-the-Collection *or* admin-on-its-
+ * workspace, and the package already answers it: `useCanManage` probes it by
+ * attempting the roster read the server gates on exactly that authority. Only
+ * `data === true` unlocks anything — a pending probe, a denial and a failure
+ * all render the same screen without management controls (fail closed).
+ *
+ * **A denial is an answer, not a failure.** `canManage` reads Connect's
+ * *numeric* code 7 as "not an authority" and returns false. A host transport
+ * that flattens errors to a bare message (core's did until
+ * knkboor/general#814) turns that answer into a rejection — which this screen
+ * survives, because a rejected probe is not `true` either, so the controls
+ * stay hidden instead of the screen breaking for the users with least access.
+ * Both shapes are pinned by test.
+ *
+ * **Grantees never see the roster** (ADR 0001 again): content access and
+ * roster access are separate privileges, so a viewer gets the Collection's
+ * identity and no Manage Access affordance at all — the roster is never
+ * fetched for them, not merely hidden after the fact. Authority withdrawn
+ * *mid-session* takes the controls away at once and closes an open dialog
+ * through its `open` prop — the machine itself stays mounted, because
+ * unmounting a dialog while it is open leaks the body scroll lock over the
+ * whole application (CLAUDE-ANKER's Modal mount pattern). The Restricted state
+ * itself is on the record they already read and is shown to everyone, as the
+ * index and the folder tree show it.
+ *
+ * **Curation** — adding and removing assets — is not this screen's job: per
+ * ADR 0003 it happens in the library, where the assets are.
+ *
+ * **The patch is the whole record this screen owns, every time.**
+ * `UpdateCollectionRequest` carries plain proto3 scalars and the service applies
+ * `description` unconditionally, so a patch naming only `name` clears the
+ * description (knkCS/mediahub#159, the same trap as knkcms/core#863). Saving
+ * therefore sends both fields, and deliberately does *not* name `rules` — the
+ * smart-collection field this surface does not edit (knkCS/mediahub#173) — so
+ * the client's read-modify-write keeps whatever is stored there.
+ *
+ * **Correct against the wire, not against the declared type.** Connect omits
+ * empty strings from its JSON, so a description-less collection arrives with
+ * the key absent. Every field is defaulted where it is read, so an absent value
+ * renders as empty rather than flipping a controlled input to uncontrolled.
+ */
+export declare function CollectionDetail({ collectionId, collectionsPath, onBack, onDeleted, }: CollectionDetailProps): default_2.JSX.Element;
+
+export declare namespace CollectionDetail {
+    var displayName: string;
+}
+
+export declare interface CollectionDetailProps {
+    /** The collection to show. */
+    collectionId: string;
+    /**
+     * Typed path of the host's collection index, used for the breadcrumb back
+     * link. The screen never routes itself — the host owns its URLs
+     * (core's `docs/service-integration.md`).
+     */
+    collectionsPath?: string;
+    /**
+     * Navigate back to the collection index. Given one, the screen renders a
+     * back affordance that confirms before discarding unsaved edits — the
+     * breadcrumb link above is the host's own navigation and the screen cannot
+     * intercept it.
+     */
+    onBack?: () => void;
+    /** Called after a successful delete; the host decides where to go next. */
+    onDeleted?: () => void;
+}
+
+/**
+ * The workspace's Collections, listed. The package owns the screen; both hosts
+ * compose it and keep their own routing to themselves (#175, parent #174).
+ *
+ * Listing is deliberately NOT gated by authority: a Collection the user can see
+ * is listed, because per ADR 0001 seeing a Collection and managing it are
+ * separate privileges. Management controls arrive in later tickets and are
+ * gated there, on the can-manage probe — never here, on the listing.
+ */
+export declare function CollectionIndex(props: CollectionIndexProps): React.JSX.Element;
+
+export declare namespace CollectionIndex {
+    var displayName: string;
+}
+
+export declare interface CollectionIndexProps {
+    /**
+     * A collection was opened. The host decides what that means — it receives
+     * the id and nothing else, because this package must not know either host's
+     * URL structure (core's `docs/service-integration.md`; spec #138, #174).
+     * Screens, not routes: nothing here navigates and nothing here builds a path.
+     */
+    onOpen?: (collectionId: string) => void;
+    /** The reader asked for a new collection. Same contract as `onOpen`. */
+    onCreate?: () => void;
+}
+
 export declare interface CollectionInfo {
     id: string;
     workspaceId: string;
@@ -1124,6 +1304,41 @@ export declare const i18nResources: {
                 discardConfirmMessage: string;
                 discardConfirmLabel: string;
             };
+            collectionDetail: {
+                breadcrumbCollections: string;
+                notFound: string;
+                untitled: string;
+                backButtonAria: string;
+                nameLabel: string;
+                nameRequired: string;
+                slugLabel: string;
+                descriptionLabel: string;
+                descriptionPlaceholder: string;
+                save: string;
+                delete: string;
+                saveSuccessToast: string;
+                saveFailedToast: string;
+                deleteConfirmTitle: string;
+                deleteConfirmMessage: string;
+                deleteConfirmLabel: string;
+                deleteSuccessToast: string;
+                deleteFailedToast: string;
+                discardConfirmTitle: string;
+                discardConfirmMessage: string;
+                discardConfirmLabel: string;
+                accessHeading: string;
+                accessOpenNote: string;
+                accessRestrictedNote: string;
+                restrict: string;
+                unrestrict: string;
+                manageAccess: string;
+                unrestrictConfirmTitle: string;
+                unrestrictConfirmLabel: string;
+                restrictSuccessToast: string;
+                unrestrictSuccessToast: string;
+                restrictFailedToast: string;
+                unrestrictFailedToast: string;
+            };
             assetLibrary: {
                 pageTitle: string;
                 uploadButton: string;
@@ -1158,6 +1373,20 @@ export declare const i18nResources: {
                 clearStatusGroup: string;
                 assetsLoadFailedHeader: string;
                 noAssetsFound: string;
+                activeFiltersLabel: string;
+                removeFilter: string;
+                clearAllFilters: string;
+                chipFolder: string;
+                chipFolderUnresolved: string;
+                chipCollection: string;
+                chipCollectionUnresolved: string;
+                chipTag: string;
+                chipTagUnresolved: string;
+                chipStatus: string;
+                chipStatusGroup: string;
+                chipSearch: string;
+                noAssetsMatchFilters: string;
+                noAssetsMatchFiltersDescription: string;
             };
             assetPicker: {
                 headerSingle: string;
@@ -1401,6 +1630,36 @@ export declare const i18nResources: {
                 noMatchesDescription: string;
                 loadFailedHeader: string;
             };
+            collectionCreate: {
+                title: string;
+                breadcrumbCollections: string;
+                nameLabel: string;
+                namePlaceholder: string;
+                nameRequired: string;
+                slugLabel: string;
+                slugHint: string;
+                slugInvalid: string;
+                descriptionLabel: string;
+                descriptionPlaceholder: string;
+                submit: string;
+                cancel: string;
+                createdToast: string;
+                createFailedToast: string;
+            };
+            collectionIndex: {
+                pageTitle: string;
+                pageSubtitle: string;
+                newButton: string;
+                searchPlaceholder: string;
+                collectionsCount: string;
+                columnName: string;
+                columnDescription: string;
+                noCollectionsHeader: string;
+                noCollectionsDescription: string;
+                noMatchesHeader: string;
+                noMatchesDescription: string;
+                loadFailedHeader: string;
+            };
             aiProcesses: {
                 intro: string;
                 newProcess: string;
@@ -1552,6 +1811,41 @@ export declare const i18nResources: {
                 discardConfirmMessage: string;
                 discardConfirmLabel: string;
             };
+            collectionDetail: {
+                breadcrumbCollections: string;
+                notFound: string;
+                untitled: string;
+                backButtonAria: string;
+                nameLabel: string;
+                nameRequired: string;
+                slugLabel: string;
+                descriptionLabel: string;
+                descriptionPlaceholder: string;
+                save: string;
+                delete: string;
+                saveSuccessToast: string;
+                saveFailedToast: string;
+                deleteConfirmTitle: string;
+                deleteConfirmMessage: string;
+                deleteConfirmLabel: string;
+                deleteSuccessToast: string;
+                deleteFailedToast: string;
+                discardConfirmTitle: string;
+                discardConfirmMessage: string;
+                discardConfirmLabel: string;
+                accessHeading: string;
+                accessOpenNote: string;
+                accessRestrictedNote: string;
+                restrict: string;
+                unrestrict: string;
+                manageAccess: string;
+                unrestrictConfirmTitle: string;
+                unrestrictConfirmLabel: string;
+                restrictSuccessToast: string;
+                unrestrictSuccessToast: string;
+                restrictFailedToast: string;
+                unrestrictFailedToast: string;
+            };
             assetLibrary: {
                 pageTitle: string;
                 uploadButton: string;
@@ -1586,6 +1880,20 @@ export declare const i18nResources: {
                 clearStatusGroup: string;
                 assetsLoadFailedHeader: string;
                 noAssetsFound: string;
+                activeFiltersLabel: string;
+                removeFilter: string;
+                clearAllFilters: string;
+                chipFolder: string;
+                chipFolderUnresolved: string;
+                chipCollection: string;
+                chipCollectionUnresolved: string;
+                chipTag: string;
+                chipTagUnresolved: string;
+                chipStatus: string;
+                chipStatusGroup: string;
+                chipSearch: string;
+                noAssetsMatchFilters: string;
+                noAssetsMatchFiltersDescription: string;
             };
             assetPicker: {
                 headerSingle: string;
@@ -1829,6 +2137,36 @@ export declare const i18nResources: {
                 noMatchesDescription: string;
                 loadFailedHeader: string;
             };
+            collectionCreate: {
+                title: string;
+                breadcrumbCollections: string;
+                nameLabel: string;
+                namePlaceholder: string;
+                nameRequired: string;
+                slugLabel: string;
+                slugHint: string;
+                slugInvalid: string;
+                descriptionLabel: string;
+                descriptionPlaceholder: string;
+                submit: string;
+                cancel: string;
+                createdToast: string;
+                createFailedToast: string;
+            };
+            collectionIndex: {
+                pageTitle: string;
+                pageSubtitle: string;
+                newButton: string;
+                searchPlaceholder: string;
+                collectionsCount: string;
+                columnName: string;
+                columnDescription: string;
+                noCollectionsHeader: string;
+                noCollectionsDescription: string;
+                noMatchesHeader: string;
+                noMatchesDescription: string;
+                loadFailedHeader: string;
+            };
             aiProcesses: {
                 intro: string;
                 newProcess: string;