@byline/cli 0.1.1

package/dist/templates/byline-examples/collections/docs/schema.ts

@@ -0,0 +1,209 @@
+/**
+ * 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 { CollectionFieldData } from '@byline/core'
+import { defineCollection, defineWorkflow } from '@byline/core'
+
+import { PhotoBlock } from '../../blocks/photo-block.js'
+import { RichTextBlock } from '../../blocks/richtext-block.js'
+import { availableLanguagesField } from '../../fields/available-languages-field.js'
+
+// ---- Schema (server-safe, no UI concerns) ----
+
+export const Docs = defineCollection({
+  path: 'docs',
+  labels: {
+    singular: 'Document',
+    plural: 'Documents',
+  },
+  // Workflow: defineWorkflow() guarantees draft, published, and archived are
+  // always present and correctly ordered. Any additional statuses specified in
+  // customStatuses are inserted between draft and published.
+  //
+  //   Resulting order: [draft, needs_review, published, archived]
+  workflow: defineWorkflow({
+    draft: { label: 'Draft', verb: 'Revert to Draft' },
+    published: { label: 'Published', verb: 'Publish' },
+    archived: { label: 'Archived', verb: 'Archive' },
+    customStatuses: [{ name: 'needs_review', label: 'Needs Review', verb: 'Request Review' }],
+  }),
+  showStats: true,
+  search: { fields: ['title'] },
+  useAsTitle: 'title',
+  useAsPath: 'title',
+  linksInEditor: true, // See type definition for details.
+  // All hooks can be a single function or an array of functions.
+  // If an array is provided, the functions will be executed in sequence.
+  hooks: {
+    beforeCreate: async ({ data, collectionPath }) => {
+      // Example: beforeCreate hook
+      console.log(
+        `beforeCreate: Creating a new document in collection ${collectionPath} with data:`,
+        data
+      )
+    },
+    afterCreate: async ({ data, collectionPath, documentId, documentVersionId }) => {
+      // Example: log the creation of a new document.
+      console.log(
+        `afterCreate: Document created with ID ${documentId} and version ID ${documentVersionId} in collection ${collectionPath}`
+      )
+    },
+    beforeUpdate: async ({ data, originalData, collectionPath }) => {
+      // Example: prevent a document from being published if it doesn't have a title.
+      console.log(
+        `beforeUpdate: Updating a document in collection ${collectionPath} with data:`,
+        data
+      )
+    },
+    afterUpdate: async ({ data, originalData, collectionPath, documentId, documentVersionId }) => {
+      // Example: log the update of a document.
+      console.log(
+        `afterUpdate: Document with ID ${documentId} and version ID ${documentVersionId} in collection ${collectionPath} was updated`
+      )
+    },
+    beforeStatusChange: async ({
+      documentId,
+      documentVersionId,
+      collectionPath,
+      previousStatus,
+      nextStatus,
+    }) => {
+      console.log(
+        `beforeStatusChange: Changing status of document in collection ${collectionPath} from ${previousStatus} to ${nextStatus} with document ID ${documentId} and version ID ${documentVersionId}`
+      )
+    },
+    afterStatusChange: async ({
+      documentId,
+      documentVersionId,
+      collectionPath,
+      previousStatus,
+      nextStatus,
+    }) => {
+      console.log(
+        `afterStatusChange: Status of document in collection ${collectionPath} changed from ${previousStatus} to ${nextStatus} with document ID ${documentId} and version ID ${documentVersionId}`
+      )
+    },
+    beforeUnpublish: async ({ documentId, collectionPath }) => {
+      console.log(
+        `beforeUnpublish: Unpublishing document in collection ${collectionPath} with document ID ${documentId}.`
+      )
+    },
+    afterUnpublish: async ({ documentId, collectionPath }) => {
+      console.log(
+        `afterUnpublish: Document in collection ${collectionPath} with document ID ${documentId} unpublished.`
+      )
+    },
+    beforeDelete: async ({ documentId, collectionPath }) => {
+      console.log(
+        `beforeDelete: Deleting document in collection ${collectionPath} with document ID ${documentId}.`
+      )
+    },
+    afterDelete: async ({ documentId, collectionPath }) => {
+      console.log(
+        `afterDelete: Document in collection ${collectionPath} with document ID ${documentId} deleted.`
+      )
+    },
+  },
+  fields: [
+    {
+      name: 'title',
+      label: 'Title',
+      type: 'text',
+      localized: true,
+      hooks: {
+        // Advisory: flag leading whitespace without altering the value.
+        beforeValidate: ({ value }) => {
+          if (typeof value === 'string' && value !== value.trimStart()) {
+            return { error: 'Title should not start with whitespace' }
+          }
+        },
+      },
+    },
+    {
+      name: 'summary',
+      label: 'Summary',
+      type: 'textArea',
+      localized: true,
+      helpText:
+        'Enter a short summary. The first 150 characters are used for social media meta descriptions. Aim for 100–300 characters.',
+    },
+    // Relation field demo. Points at the Media upload collection
+    // so editors can choose a feature image via the relation picker widget.
+    // Set `displayField: 'title'` so the picker's row label reads from the
+    // uploaded item's `title` field rather than falling back to its path.
+    // Will display the picker defined columns if present in the admin.tsx
+    // configuration.
+    {
+      name: 'featureImage',
+      label: 'Feature Image',
+      type: 'relation',
+      targetCollection: 'media',
+      displayField: 'title',
+      optional: true,
+    },
+    {
+      name: 'publishedOn',
+      label: 'Published On',
+      type: 'datetime',
+      mode: 'datetime',
+    },
+    {
+      name: 'category',
+      label: 'Category',
+      type: 'relation',
+      targetCollection: 'docs-categories',
+      displayField: 'name',
+    },
+    {
+      name: 'featured',
+      label: 'Featured',
+      type: 'checkbox',
+      optional: true,
+      helpText: 'Feature this document.',
+    },
+    {
+      name: 'content',
+      label: 'Content',
+      type: 'blocks',
+      optional: true,
+      blocks: [RichTextBlock, PhotoBlock],
+    },
+    {
+      name: 'reviews',
+      label: 'Reviews',
+      type: 'array',
+      optional: true,
+      fields: [
+        {
+          name: 'reviewItem',
+          label: 'Review Item',
+          type: 'group',
+          fields: [
+            { name: 'rating', label: 'Rating', type: 'integer' },
+            {
+              name: 'comment',
+              label: 'Comments',
+              type: 'richText',
+              localized: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'links',
+      label: 'Links',
+      type: 'array',
+      optional: true,
+      fields: [{ name: 'link', label: 'Link', type: 'text' }],
+    },
+    availableLanguagesField(),
+  ],
+})
+
+export type DocFields = CollectionFieldData<typeof Docs>

package/dist/templates/byline-examples/collections/docs-categories/admin.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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, type ColumnDefinition, defineAdmin } from '@byline/core'
+import { DateTimeFormatter } from '@byline/ui/react/fields'
+
+import { DocsCategories } from './schema.js'
+
+// ---- Admin UI config (client-only, presentation concerns) ----
+
+/**
+ * Column definitions for the default table-based list view.
+ *
+ * These are passed to the built-in `ListView` component and control which
+ * fields appear as columns, their labels, sort behaviour, and formatters.
+ *
+ * Note: when a custom `listView` component is registered on the
+ * `CollectionAdminConfig`, it receives the raw paginated data directly and
+ * is responsible for its own layout. These column definitions can still
+ * be used in a custom list view, but they are not automatically applied
+ * as they are with the default table-based `ListView`. You can import
+ * them if needed - for example if you wanted to create a toggled grid/table
+ * custom view.
+ */
+
+const listViewColumns: ColumnDefinition[] = [
+  {
+    fieldName: 'name',
+    label: 'Name',
+    sortable: true,
+    align: 'left',
+    className: 'w-[25%]',
+  },
+  {
+    fieldName: 'status',
+    label: 'Status',
+    align: 'center',
+    className: 'w-[15%]',
+  },
+  {
+    fieldName: 'updatedAt',
+    label: 'Last Updated',
+    sortable: true,
+    align: 'right',
+    className: 'w-[20%]',
+    formatter: { component: DateTimeFormatter },
+  },
+]
+
+/**
+ * Columns rendered per row when Media appears as the target of a relation
+ * picker (e.g. News → `heroImage` → Media). Narrower than the list view —
+ * just enough to identify the right media item at a glance.
+ */
+const pickerViewColumns: ColumnDefinition[] = [
+  {
+    fieldName: 'name',
+    label: 'Name',
+    align: 'left',
+    className: 'flex-1',
+  },
+  {
+    fieldName: 'status',
+    label: 'Status',
+    align: 'right',
+    className: 'w-[80px] shrink-0 text-xs text-gray-500',
+  },
+]
+
+export const DocsCategoriesAdmin: CollectionAdminConfig = defineAdmin(DocsCategories, {
+  columns: listViewColumns,
+  picker: pickerViewColumns,
+})

package/dist/templates/byline-examples/collections/docs-categories/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { DocsCategoriesAdmin } from './admin.js'
+export { DocsCategories } from './schema.js'

package/dist/templates/byline-examples/collections/docs-categories/schema.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { CollectionFieldData } from '@byline/core'
+import { defineCollection, SINGLE_STATUS_WORKFLOW } from '@byline/core'
+
+// ---- Schema (server-safe, no UI concerns) ----
+
+export const DocsCategories = defineCollection({
+  path: 'docs-categories',
+  labels: {
+    singular: 'Document Category',
+    plural: 'Document Categories',
+  },
+  // Lookup collection — no editorial lifecycle. Saves go straight to
+  // `published` and the form shows only Save / Close.
+  workflow: SINGLE_STATUS_WORKFLOW,
+  showStats: true,
+  search: { fields: ['name'] },
+  useAsTitle: 'name',
+  useAsPath: 'name',
+  fields: [
+    { name: 'name', label: 'Name', type: 'text', localized: true },
+    { name: 'description', label: 'Description', type: 'textArea', localized: true },
+  ],
+})
+
+export type DocsCategoryFields = CollectionFieldData<typeof DocsCategories>

package/dist/templates/byline-examples/collections/media/admin.tsx

@@ -0,0 +1,188 @@
+/**
+ * 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, type ColumnDefinition, defineAdmin } from '@byline/core'
+import { DateTimeFormatter } from '@byline/ui/react/fields'
+
+import { MediaListView } from './components/media-list-view.js'
+import { MediaThumbnail } from './components/media-thumbnail.js'
+import { Media } from './schema.js'
+
+/**
+ * Column definitions for the default table-based list view.
+ *
+ * These are passed to the built-in `ListView` component and control which
+ * fields appear as columns, their labels, sort behaviour, and formatters.
+ *
+ * Note: when a custom `listView` component is registered on the
+ * `CollectionAdminConfig`, it receives the raw paginated data directly and
+ * is responsible for its own layout. These column definitions can still
+ * be used in a custom list view, but they are not automatically applied
+ * as they are with the default table-based `ListView`. You can import
+ * them if needed - for example if you wanted to create a toggled grid/table
+ * custom view.
+ */
+const listViewColumns: ColumnDefinition[] = [
+  {
+    fieldName: 'image' as keyof any,
+    label: 'Preview',
+    align: 'left',
+    className: 'w-[5%]',
+    formatter: { component: MediaThumbnail },
+  },
+  {
+    fieldName: 'title',
+    label: 'Title',
+    sortable: true,
+    align: 'left',
+    className: 'w-[60%]',
+  },
+  {
+    fieldName: 'status',
+    label: 'Status',
+    align: 'center',
+    className: 'w-[15%]',
+  },
+  {
+    fieldName: 'updatedAt',
+    label: 'Last Updated',
+    sortable: true,
+    align: 'right',
+    className: 'w-[20%]',
+    formatter: { component: DateTimeFormatter },
+  },
+]
+
+/**
+ * Columns rendered per row when Media appears as the target of a relation
+ * picker (e.g. News → `heroImage` → Media). Narrower than the list view —
+ * just enough to identify the right media item at a glance.
+ */
+const pickerViewColumns: ColumnDefinition[] = [
+  {
+    fieldName: 'image' as keyof any,
+    label: 'Preview',
+    align: 'left',
+    className: 'w-[72px] shrink-0',
+    formatter: { component: MediaThumbnail },
+  },
+  {
+    fieldName: 'title',
+    label: 'Title',
+    align: 'left',
+    className: 'flex-1',
+  },
+  {
+    fieldName: 'status',
+    label: 'Status',
+    align: 'right',
+    className: 'w-[80px] shrink-0 text-xs text-gray-500',
+  },
+]
+
+export const MediaAdmin: CollectionAdminConfig = defineAdmin(Media, {
+  /**
+   * Column definitions for the default table-based list view.
+   * Controls which fields appear as columns, their labels, sort behaviour, and formatters.
+   */
+  columns: listViewColumns,
+
+  /**
+   * Column definitions used when this collection appears as the target of a relation
+   * picker modal (opened from a `relation` field widget). Omit to fall back to a
+   * single-line render of `useAsTitle` + `path`.
+   *
+   * Shape matches `ColumnDefinition` so formatters can be reused across list and picker.
+   */
+  picker: pickerViewColumns,
+
+  /**
+   * Custom list-view component that completely replaces the default table-based `ListView`
+   * on the collection index route. Receives a `ListViewComponentProps` object and is
+   * responsible for rendering search, ordering, results, and pagination itself.
+   */
+  listView: MediaListView,
+
+  /**
+   * Group name for organising this collection in the admin sidebar navigation.
+   *
+   * @example
+   * group: 'Assets',
+   */
+  // group: undefined,
+
+  /**
+   * Per-field rendering overrides, keyed by field name. Use to supply custom
+   * UI component slots for a specific field without affecting placement.
+   * Placement is controlled exclusively through the layout primitives below.
+   *
+   * @example
+   * fields: { title: { components: { Input: MyCustomInput } } }
+   */
+  // fields: {},
+
+  /**
+   * Preview URL builder for live preview links. Receives the document and an
+   * optional locale and should return a fully-qualified URL string.
+   *
+   * @example
+   * preview: (doc, { locale }) => `https://example.com/media/${doc.fields.path}`
+   */
+  // preview: undefined,
+
+  // ---------------------------------------------------------------------------
+  // UI Layout
+  //
+  // Tab, row, and group containers control how fields are grouped and positioned
+  // in the document edit view. Field names must match those defined in the
+  // collection schema. Names for tabSets, rows, and groups must be unique and
+  // must not collide with any schema field name (a startup error is thrown if
+  // they do).
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Named tab sets. Each entry creates a separate tabbed interface in the edit
+   * view. You can define more than one tab set, though a single set is sufficient
+   * for most collections. Tab sets may only appear in `layout.main`.
+   *
+   * Each tab's `fields` array accepts schema field names, row names, and group names.
+   * An optional `condition` function can show/hide a tab based on live form data.
+   */
+  // tabSets: [],
+
+  /**
+   * Named horizontal-row layouts. Fields listed inside a row are rendered
+   * side-by-side (flex row) on desktop and stack vertically below the `sm`
+   * breakpoint. Rows are leaf containers — they accept only schema field names.
+   *
+   * Reference a row by its `name` inside a tab's `fields`, a group's `fields`,
+   * or directly in `layout.main` / `layout.sidebar`.
+   */
+  // rows: [],
+
+  /**
+   * Named labelled-fieldset clusters. Groups accept schema field names and row
+   * names (not tabSets or nested groups). An optional `label` renders a heading
+   * above the cluster.
+   *
+   * Reference a group by its `name` inside a tab's `fields` or directly in
+   * `layout.main` / `layout.sidebar`.
+   */
+  // groups: [],
+
+  /**
+   * Composition of all layout primitives into the form's two render regions.
+   *
+   * - `main` — accepts tabSet names, group names, row names, and schema field names.
+   * - `sidebar` — accepts group names, row names, and schema field names (no tabSets).
+   *
+   * When omitted entirely, the renderer synthesises a default that places every
+   * schema field in `main` in declaration order.
+   */
+  // layout: { main: [], sidebar: [] },
+})