@byline/core 4.13.0 → 4.14.0

package/dist/@types/admin-types.d.ts

@@ -167,6 +167,31 @@ export interface FieldAdminConfig {
      */
     editor?: RichTextEditorComponent;
 }
+/**
+ * One labelled group of collections on the admin dashboard.
+ *
+ * Declared in display order on `AdminConfig.collectionGroups` and referenced by
+ * `name` from `CollectionAdminConfig.group`. Array order is the order headings
+ * appear on the dashboard; a group with no member collections is not rendered
+ * at all, so no heading ever sits above an empty section.
+ */
+export interface CollectionGroupDefinition {
+    /**
+     * Stable key referenced by `CollectionAdminConfig.group`. Boot-validated —
+     * a reference to an undeclared name throws at startup rather than silently
+     * producing an extra heading.
+     */
+    name: string;
+    /**
+     * Heading text rendered above this group's collections.
+     *
+     * A plain string, deliberately not translated: `CollectionDefinition.labels`
+     * are themselves rendered untranslated on the dashboard, so translating group
+     * headings alone would put a localised heading above English card titles.
+     * Translated headings belong to a later, uniform collection-label i18n pass.
+     */
+    label: string;
+}
 /**
  * Minimal document shape passed to `CollectionAdminConfig.preview.url`.
  *
@@ -193,7 +218,15 @@ export interface PreviewDocument<F = any> {
 export interface CollectionAdminConfig<T = any> {
     /** Must match the `path` of the corresponding `CollectionDefinition`. */
     slug: string;
-    /** Group name for organising collections in the admin sidebar. */
+    /**
+     * Dashboard group this collection belongs to. Must name an entry in
+     * `AdminConfig.collectionGroups`; an unknown name throws at startup.
+     *
+     * Omit to place the collection in the leading ungrouped band, which renders
+     * above the first group heading with no heading of its own.
+     *
+     * @see CollectionGroupDefinition
+     */
     group?: string;
     /** Column definitions for the collection list view. */
     columns?: ColumnDefinition<T>[];

package/dist/@types/site-config.d.ts

@@ -8,7 +8,7 @@
 import type { SessionProvider } from '@byline/auth';
 import type { SlugifierFn } from '../utils/slugify.js';
 import type { FilenameSlugifierFn } from '../utils/slugify-filename.js';
-import type { BlockAdminConfig, CollectionAdminConfig } from './admin-types.js';
+import type { BlockAdminConfig, CollectionAdminConfig, CollectionGroupDefinition } from './admin-types.js';
 import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, UploadHooks, UploadHooksLoader } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
 import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn, RichTextToTextFn } from './field-types.js';
@@ -146,6 +146,20 @@ export type TranslationBundleShape = Readonly<{
 export interface AdminConfig extends BaseConfig {
     /** Admin UI configuration for collections (client-side only). */
     admin?: CollectionAdminConfig[];
+    /**
+     * Ordered registry of dashboard collection groups. Array order is display
+     * order. A collection joins a group by setting `CollectionAdminConfig.group`
+     * to an entry's `name`.
+     *
+     * Omit entirely to keep the flat, ungrouped dashboard grid — this property is
+     * purely additive and changes nothing when absent.
+     *
+     * Boot-validated by `validateAdminConfigs`: duplicate names, blank names or
+     * labels, and references to undeclared names all throw.
+     *
+     * @see CollectionGroupDefinition
+     */
+    collectionGroups?: CollectionGroupDefinition[];
     /**
      * Admin UI configuration for blocks, keyed by `blockType` — the block-scoped
      * analogue of `admin`. Because blocks are shared across collections, an

package/dist/auth/filter-readable-collections.d.ts

@@ -0,0 +1,37 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { CollectionDefinition } from '../@types/collection-types.js';
+/**
+ * The ability facts a rendering surface needs about the current administrator.
+ * Mirrors the snapshot the admin route places on router context in
+ * `beforeLoad` — deliberately a plain data shape so this module stays
+ * React-free and transport-agnostic.
+ */
+export interface ActorAbilitySnapshot {
+    isSuperAdmin: boolean;
+    abilities: readonly string[];
+}
+/**
+ * Narrow a collection list to those the administrator can read.
+ *
+ * `read` is the gate because everything a dashboard card offers — the link to
+ * the list view, and the per-status counts — requires
+ * `collections.<path>.read` and is rejected server-side without it. An
+ * administrator who cannot read a collection would otherwise see a card whose
+ * status tiles all read zero, which is indistinguishable from a collection that
+ * is genuinely empty.
+ *
+ * **Cosmetic only.** This is an affordance, never a security boundary.
+ * `assertActorCanPerform` remains the enforcement point on every read and write
+ * path; hiding a card only stops the interface advertising something the server
+ * will refuse. Never rely on this function to keep data from anyone.
+ *
+ * Super-admin short-circuits, mirroring `AdminAuth.assertAbility` and the
+ * client-side `useAbilities` hook.
+ */
+export declare function filterReadableCollections(collections: readonly CollectionDefinition[], snapshot: ActorAbilitySnapshot): CollectionDefinition[];

package/dist/auth/filter-readable-collections.js

@@ -0,0 +1,32 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { collectionAbilityKey } from './register-collection-abilities.js';
+/**
+ * Narrow a collection list to those the administrator can read.
+ *
+ * `read` is the gate because everything a dashboard card offers — the link to
+ * the list view, and the per-status counts — requires
+ * `collections.<path>.read` and is rejected server-side without it. An
+ * administrator who cannot read a collection would otherwise see a card whose
+ * status tiles all read zero, which is indistinguishable from a collection that
+ * is genuinely empty.
+ *
+ * **Cosmetic only.** This is an affordance, never a security boundary.
+ * `assertActorCanPerform` remains the enforcement point on every read and write
+ * path; hiding a card only stops the interface advertising something the server
+ * will refuse. Never rely on this function to keep data from anyone.
+ *
+ * Super-admin short-circuits, mirroring `AdminAuth.assertAbility` and the
+ * client-side `useAbilities` hook.
+ */
+export function filterReadableCollections(collections, snapshot) {
+    if (snapshot.isSuperAdmin)
+        return [...collections];
+    const held = new Set(snapshot.abilities);
+    return collections.filter((collection) => held.has(collectionAbilityKey(collection.path, 'read')));
+}

package/dist/auth/filter-readable-collections.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/auth/filter-readable-collections.test.node.js

@@ -0,0 +1,72 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { filterReadableCollections } from './filter-readable-collections.js';
+const define = (path) => ({
+    path,
+    labels: { singular: path, plural: path },
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
+const news = define('news');
+const pages = define('pages');
+const media = define('media');
+const all = [news, pages, media];
+describe('filterReadableCollections', () => {
+    it('returns every collection for a super admin, regardless of abilities', () => {
+        expect(filterReadableCollections(all, { isSuperAdmin: true, abilities: [] })).toEqual(all);
+    });
+    it('returns nothing when the actor holds no abilities', () => {
+        expect(filterReadableCollections(all, { isSuperAdmin: false, abilities: [] })).toEqual([]);
+    });
+    it('returns only the collections whose read ability is held', () => {
+        const result = filterReadableCollections(all, {
+            isSuperAdmin: false,
+            abilities: ['collections.news.read', 'collections.media.read'],
+        });
+        expect(result).toEqual([news, media]);
+    });
+    it('preserves declaration order', () => {
+        const result = filterReadableCollections(all, {
+            isSuperAdmin: false,
+            abilities: ['collections.media.read', 'collections.news.read'],
+        });
+        expect(result.map((c) => c.path)).toEqual(['news', 'media']);
+    });
+    it('does not treat a non-read verb as granting visibility', () => {
+        const result = filterReadableCollections(all, {
+            isSuperAdmin: false,
+            abilities: [
+                'collections.news.create',
+                'collections.news.update',
+                'collections.news.publish',
+                'collections.news.delete',
+                'collections.news.changeStatus',
+                'collections.news.reindex',
+            ],
+        });
+        expect(result).toEqual([]);
+    });
+    it('does not match on a prefix of a collection path', () => {
+        const result = filterReadableCollections([define('news-categories')], {
+            isSuperAdmin: false,
+            abilities: ['collections.news.read'],
+        });
+        expect(result).toEqual([]);
+    });
+    it('ignores unrelated admin abilities', () => {
+        const result = filterReadableCollections(all, {
+            isSuperAdmin: false,
+            abilities: ['admin.users.read', 'admin.roles.read'],
+        });
+        expect(result).toEqual([]);
+    });
+    it('returns a new array rather than the input', () => {
+        const result = filterReadableCollections(all, { isSuperAdmin: true, abilities: [] });
+        expect(result).not.toBe(all);
+    });
+});

package/dist/auth/index.d.ts

@@ -7,4 +7,5 @@
  */
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
+export { type ActorAbilitySnapshot, filterReadableCollections, } from './filter-readable-collections.js';
 export { COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';

package/dist/auth/index.js

@@ -7,4 +7,5 @@
  */
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
+export { filterReadableCollections, } from './filter-readable-collections.js';
 export { COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';

package/dist/config/config.js

@@ -59,7 +59,7 @@ export const getCollectionAdminConfig = (slug) => {
 };
 export function defineAdminConfig(config) {
     validateCollections(config.collections);
-    validateAdminConfigs(config.admin, config.collections);
+    validateAdminConfigs(config.admin, config.collections, config.collectionGroups);
     validateBlockAdminConfigs(config.blockAdmin, config.collections);
     const resolved = { ...config, routes: resolveRoutes(config.routes) };
     setAdminConfigInstance(resolved);

package/dist/config/group-collections.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { CollectionAdminConfig, CollectionGroupDefinition } from '../@types/admin-types.js';
+import type { CollectionDefinition } from '../@types/collection-types.js';
+/**
+ * One renderable section of the admin dashboard: a heading (or none) and the
+ * collections beneath it.
+ */
+export interface CollectionGroupBucket {
+    /** Registry key, or `null` for the leading ungrouped band. */
+    name: string | null;
+    /** Heading text, or `null` when the band renders without a heading. */
+    label: string | null;
+    collections: CollectionDefinition[];
+}
+/**
+ * Bucket collections into ordered dashboard sections.
+ *
+ * Rules:
+ *  - The ungrouped band is emitted first, and omitted entirely when empty.
+ *  - Declared groups follow in `collectionGroups` order.
+ *  - A declared group with no members is skipped, so no heading ever appears
+ *    above an empty section.
+ *  - Collection declaration order is preserved within each bucket.
+ *  - An absent or empty registry yields a single ungrouped bucket holding every
+ *    collection — the flat grid Byline rendered before groups existed.
+ *
+ * This function is deliberately total: a `group` naming no declared entry is
+ * treated as ungrouped rather than throwing. `validateCollectionGroups` rejects
+ * that configuration at startup, so the fallback only ever covers a stale or
+ * hand-built config object, where crashing the dashboard would be the worse
+ * outcome.
+ *
+ * It takes no actor and knows nothing about abilities. Callers that need to
+ * hide collections filter the `collections` argument first — see
+ * `filterReadableCollections`. That ordering is what makes a group whose
+ * members are all hidden disappear along with its heading: it arrives here with
+ * no members and is skipped by the rule above.
+ */
+export declare function groupCollectionsForAdmin(collections: readonly CollectionDefinition[], admin: readonly CollectionAdminConfig[] | undefined, collectionGroups: readonly CollectionGroupDefinition[] | undefined): CollectionGroupBucket[];

package/dist/config/group-collections.js

@@ -0,0 +1,63 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Bucket collections into ordered dashboard sections.
+ *
+ * Rules:
+ *  - The ungrouped band is emitted first, and omitted entirely when empty.
+ *  - Declared groups follow in `collectionGroups` order.
+ *  - A declared group with no members is skipped, so no heading ever appears
+ *    above an empty section.
+ *  - Collection declaration order is preserved within each bucket.
+ *  - An absent or empty registry yields a single ungrouped bucket holding every
+ *    collection — the flat grid Byline rendered before groups existed.
+ *
+ * This function is deliberately total: a `group` naming no declared entry is
+ * treated as ungrouped rather than throwing. `validateCollectionGroups` rejects
+ * that configuration at startup, so the fallback only ever covers a stale or
+ * hand-built config object, where crashing the dashboard would be the worse
+ * outcome.
+ *
+ * It takes no actor and knows nothing about abilities. Callers that need to
+ * hide collections filter the `collections` argument first — see
+ * `filterReadableCollections`. That ordering is what makes a group whose
+ * members are all hidden disappear along with its heading: it arrives here with
+ * no members and is skipped by the rule above.
+ */
+export function groupCollectionsForAdmin(collections, admin, collectionGroups) {
+    const groupByCollectionPath = new Map();
+    for (const entry of admin ?? []) {
+        if (entry.group != null)
+            groupByCollectionPath.set(entry.slug, entry.group);
+    }
+    const membersByGroup = new Map();
+    for (const group of collectionGroups ?? []) {
+        membersByGroup.set(group.name, []);
+    }
+    const ungrouped = [];
+    for (const collection of collections) {
+        const groupName = groupByCollectionPath.get(collection.path);
+        const members = groupName == null ? undefined : membersByGroup.get(groupName);
+        if (members == null) {
+            ungrouped.push(collection);
+            continue;
+        }
+        members.push(collection);
+    }
+    const buckets = [];
+    if (ungrouped.length > 0) {
+        buckets.push({ name: null, label: null, collections: ungrouped });
+    }
+    for (const group of collectionGroups ?? []) {
+        const members = membersByGroup.get(group.name) ?? [];
+        if (members.length === 0)
+            continue;
+        buckets.push({ name: group.name, label: group.label, collections: members });
+    }
+    return buckets;
+}

package/dist/config/group-collections.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/config/group-collections.test.node.js

@@ -0,0 +1,81 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { groupCollectionsForAdmin } from './group-collections.js';
+const define = (path) => ({
+    path,
+    labels: { singular: path, plural: path },
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
+const pages = define('pages');
+const news = define('news');
+const images = define('images');
+const authors = define('authors');
+const categories = define('categories');
+const groups = [
+    { name: 'media', label: 'Media' },
+    { name: 'authorities', label: 'People & Organisations' },
+    { name: 'taxonomy', label: 'Taxonomies' },
+];
+const admin = [
+    { slug: 'images', group: 'media' },
+    { slug: 'authors', group: 'authorities' },
+    { slug: 'categories', group: 'taxonomy' },
+];
+describe('groupCollectionsForAdmin', () => {
+    it('returns one ungrouped bucket when no registry is declared', () => {
+        const result = groupCollectionsForAdmin([pages, news], admin, undefined);
+        expect(result).toEqual([{ name: null, label: null, collections: [pages, news] }]);
+    });
+    it('returns one ungrouped bucket when the registry is empty', () => {
+        const result = groupCollectionsForAdmin([pages, news], admin, []);
+        expect(result).toEqual([{ name: null, label: null, collections: [pages, news] }]);
+    });
+    it('emits the ungrouped band first, then groups in registry order', () => {
+        const result = groupCollectionsForAdmin([images, pages, categories, news, authors], admin, groups);
+        expect(result.map((b) => b.name)).toEqual([null, 'media', 'authorities', 'taxonomy']);
+    });
+    it('omits the ungrouped bucket entirely when every collection is grouped', () => {
+        const result = groupCollectionsForAdmin([images, authors, categories], admin, groups);
+        expect(result.map((b) => b.name)).toEqual(['media', 'authorities', 'taxonomy']);
+    });
+    it('skips a declared group that has no member collections', () => {
+        const result = groupCollectionsForAdmin([images, categories], admin, groups);
+        expect(result.map((b) => b.name)).toEqual(['media', 'taxonomy']);
+    });
+    it('returns an empty array when there are no collections at all', () => {
+        expect(groupCollectionsForAdmin([], admin, groups)).toEqual([]);
+    });
+    it('carries each group label through to its bucket', () => {
+        const result = groupCollectionsForAdmin([authors], admin, groups);
+        expect(result[0]).toEqual({
+            name: 'authorities',
+            label: 'People & Organisations',
+            collections: [authors],
+        });
+    });
+    it('preserves collection declaration order within a bucket', () => {
+        const more = define('videos');
+        const result = groupCollectionsForAdmin([more, images], [...admin, { slug: 'videos', group: 'media' }], groups);
+        expect(result[0]?.collections).toEqual([more, images]);
+    });
+    it('places a collection with no admin config in the ungrouped band', () => {
+        const result = groupCollectionsForAdmin([pages, images], admin, groups);
+        expect(result[0]).toEqual({ name: null, label: null, collections: [pages] });
+    });
+    it('treats an undeclared group name as ungrouped rather than throwing', () => {
+        // Boot validation rejects this configuration, but the function stays total
+        // so a renderer can never crash on a stale or hand-built config object.
+        const result = groupCollectionsForAdmin([pages], [{ slug: 'pages', group: 'ghost' }], groups);
+        expect(result).toEqual([{ name: null, label: null, collections: [pages] }]);
+    });
+    it('ignores admin configs whose collection is not registered', () => {
+        const result = groupCollectionsForAdmin([pages], admin, groups);
+        expect(result).toEqual([{ name: null, label: null, collections: [pages] }]);
+    });
+});

package/dist/config/validate-admin-configs.d.ts

@@ -5,7 +5,22 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition } from '../@types/index.js';
+import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition, CollectionGroupDefinition } from '../@types/index.js';
+/**
+ * Validate the dashboard collection-group registry and every reference to it.
+ *
+ * Enforced rules:
+ *  1. Each `collectionGroups` entry has a non-blank `name` and `label`.
+ *  2. No two entries share a `name`.
+ *  3. Every `CollectionAdminConfig.group` names a declared entry. This single
+ *     rule covers both a typographical error and the case where `group` was set
+ *     but the registry was never declared.
+ *
+ * Throws a plain `Error` for the same reason the rest of this module does —
+ * configuration validation runs at startup, before the logger and error
+ * registry are necessarily wired up.
+ */
+export declare function validateCollectionGroups(collectionGroups: readonly CollectionGroupDefinition[] | undefined, admins: readonly CollectionAdminConfig[] | undefined): void;
 /**
  * Validate every admin config in a configuration.
  *
@@ -30,12 +45,15 @@ import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition } fr
  *     direction (when given) is `asc` | `desc`, and the option is rejected
  *     on `orderable: true` collections (manual ordering owns their default
  *     sort and the drag-to-reorder canonical-view check assumes it).
+ *  8. Collection groups — the `collectionGroups` registry is well-formed
+ *     (non-blank, unique names) and every `admin.group` names a declared
+ *     entry. See `validateCollectionGroups`.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
  * necessarily wired up.
  */
-export declare function validateAdminConfigs(admins: readonly CollectionAdminConfig[] | undefined, collections: readonly CollectionDefinition[]): void;
+export declare function validateAdminConfigs(admins: readonly CollectionAdminConfig[] | undefined, collections: readonly CollectionDefinition[], collectionGroups?: readonly CollectionGroupDefinition[]): void;
 /**
  * Validate every block admin config in a configuration.
  *

package/dist/config/validate-admin-configs.js

@@ -38,6 +38,47 @@ function validateFieldAdminKeys(keys, resolve, fail) {
         }
     }
 }
+/**
+ * Validate the dashboard collection-group registry and every reference to it.
+ *
+ * Enforced rules:
+ *  1. Each `collectionGroups` entry has a non-blank `name` and `label`.
+ *  2. No two entries share a `name`.
+ *  3. Every `CollectionAdminConfig.group` names a declared entry. This single
+ *     rule covers both a typographical error and the case where `group` was set
+ *     but the registry was never declared.
+ *
+ * Throws a plain `Error` for the same reason the rest of this module does —
+ * configuration validation runs at startup, before the logger and error
+ * registry are necessarily wired up.
+ */
+export function validateCollectionGroups(collectionGroups, admins) {
+    const declared = new Set();
+    for (const group of collectionGroups ?? []) {
+        const name = typeof group.name === 'string' ? group.name.trim() : '';
+        const label = typeof group.label === 'string' ? group.label.trim() : '';
+        if (name === '') {
+            throw new Error('A `collectionGroups` entry has a blank `name`. Each entry needs a non-empty key for `CollectionAdminConfig.group` to reference.');
+        }
+        if (label === '') {
+            throw new Error(`Collection group "${name}" has a blank \`label\`. The label is the heading rendered above the group on the dashboard.`);
+        }
+        if (declared.has(name)) {
+            throw new Error(`Collection group "${name}" is declared more than once in \`collectionGroups\`. Group names must be unique.`);
+        }
+        declared.add(name);
+    }
+    for (const admin of admins ?? []) {
+        if (admin.group == null)
+            continue;
+        if (declared.has(admin.group))
+            continue;
+        const known = declared.size === 0
+            ? '`collectionGroups` was not declared, or is empty'
+            : `declared groups: ${[...declared].map((name) => `"${name}"`).join(', ')}`;
+        throw new Error(`Collection "${admin.slug}": \`group: '${admin.group}'\` does not name a declared collection group (${known}). Add it to \`AdminConfig.collectionGroups\`, or remove the \`group\` property.`);
+    }
+}
 /**
  * Validate every admin config in a configuration.
  *
@@ -62,12 +103,18 @@ function validateFieldAdminKeys(keys, resolve, fail) {
  *     direction (when given) is `asc` | `desc`, and the option is rejected
  *     on `orderable: true` collections (manual ordering owns their default
  *     sort and the drag-to-reorder canonical-view check assumes it).
+ *  8. Collection groups — the `collectionGroups` registry is well-formed
+ *     (non-blank, unique names) and every `admin.group` names a declared
+ *     entry. See `validateCollectionGroups`.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
  * necessarily wired up.
  */
-export function validateAdminConfigs(admins, collections) {
+export function validateAdminConfigs(admins, collections, collectionGroups) {
+    // Registry sanity runs before the early return below, so a malformed registry
+    // still fails fast in an installation that declares no admin configs.
+    validateCollectionGroups(collectionGroups, admins);
     if (admins == null || admins.length === 0)
         return;
     const collectionsByPath = new Map();

package/dist/config/validate-admin-configs.test.node.js

@@ -461,3 +461,46 @@ describe('validateBlockAdminConfigs', () => {
         expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { quoteText: {}, attribution: {} } }], [blockCollection, other])).not.toThrow();
     });
 });
+describe('validateAdminConfigs — collection groups', () => {
+    const groups = [
+        { name: 'media', label: 'Media' },
+        { name: 'taxonomy', label: 'Taxonomies' },
+    ];
+    it('accepts a valid registry and a valid reference', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news', group: 'media' }], [collection], groups)).not.toThrow();
+    });
+    it('accepts a collection with no group when a registry is declared', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], groups)).not.toThrow();
+    });
+    it('is a no-op when no registry and no group references are present', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection])).not.toThrow();
+    });
+    it('rejects a duplicate group name', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [
+            { name: 'media', label: 'Media' },
+            { name: 'media', label: 'Media Library' },
+        ])).toThrow(/declared more than once/);
+    });
+    it('rejects a blank group name', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [{ name: '  ', label: 'Media' }])).toThrow(/blank `name`/);
+    });
+    it('rejects a blank group label', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [{ name: 'media', label: '' }])).toThrow(/blank `label`/);
+    });
+    it('rejects a group reference that names no declared group', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news', group: 'medai' }], [collection], groups)).toThrow(/does not name a declared collection group/);
+    });
+    it('names the declared groups in the unresolved-reference error', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news', group: 'medai' }], [collection], groups)).toThrow(/"media", "taxonomy"/);
+    });
+    it('rejects a group reference when no registry was declared at all', () => {
+        expect(() => validateAdminConfigs([{ slug: 'news', group: 'media' }], [collection])).toThrow(/was not declared/);
+    });
+    // Registry sanity must not be skipped by the `admins` early return.
+    it('validates the registry even when there are no admin configs', () => {
+        expect(() => validateAdminConfigs([], [collection], [
+            { name: 'media', label: 'Media' },
+            { name: 'media', label: 'Media Library' },
+        ])).toThrow(/declared more than once/);
+    });
+});

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
+export { type ActorAbilitySnapshot, applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, filterReadableCollections, registerCollectionAbilities, } from './auth/index.js';
 export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { type CollectionGroupBucket, groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';

package/dist/index.js

@@ -15,10 +15,11 @@
 // through this main entry or `@byline/client`.
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
+export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, filterReadableCollections, registerCollectionAbilities, } from './auth/index.js';
 export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -82,7 +82,7 @@
     "sharp": "^0.35.3",
     "uuid": "^14.0.2",
     "zod": "^4.4.3",
-    "@byline/auth": "4.13.0"
+    "@byline/auth": "4.14.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.9",