@portabletext/astro 0.0.0 → 0.1.0

package/lib/types.ts

@@ -0,0 +1,469 @@
+import type {
+  ToolkitListNestMode,
+  ToolkitNestedPortableTextSpan,
+  ToolkitPortableTextList,
+  ToolkitPortableTextListItem,
+  ToolkitTextNode,
+} from '@portabletext/toolkit'
+import type {
+  ArbitraryTypedObject,
+  PortableTextBlock,
+  PortableTextBlockStyle,
+  PortableTextMarkDefinition,
+  TypedObject,
+} from '@portabletext/types'
+
+export type {TypedObject} from '@portabletext/types'
+
+/**
+ * Properties for the `PortableText` component
+ *
+ * @typeParam Value - Type of Portable Text payload
+ */
+export interface PortableTextProps<
+  Value extends TypedObject = PortableTextBlock | ArbitraryTypedObject,
+> {
+  /**
+   * Portable Text payload
+   */
+  value: Value | Value[]
+
+  /**
+   * Components for rendering
+   */
+  components?: SomePortableTextComponents
+
+  /**
+   * Function to call when faced with unknown types.
+   *
+   * @remarks
+   * - Prints a warning message to the console by default.
+   * - Use `false` to disable.
+   */
+  onMissingComponent?: MissingComponentHandler | boolean
+
+  /**
+   * Defines the nesting mode for lists. The value can be `html` or `direct`, and defaults to `html`.
+   *
+   * @remarks
+   * - `html` - Deeper list nodes will appear as a child of the last list item in the parent list
+   * - `direct` - Deeper list nodes will appear as a direct child of the parent list
+   *
+   * @see {@link https://portabletext.github.io/toolkit/types/ToolkitListNestMode.html ToolkitListNestMode}
+   */
+  listNestingMode?: ToolkitListNestMode
+}
+
+/**
+ * Defines how Portable Text types should be rendered.
+ */
+export interface PortableTextComponents {
+  /**
+   * Component or mapping of components for rendering `custom` types.
+   */
+  type: ComponentOrRecord
+  /**
+   * Used when a {@link PortableTextComponents.type type} component isn't found.
+   */
+  unknownType: Component
+  /**
+   * Component or mapping of components for rendering `block` styles.
+   */
+  block: ComponentOrRecord<Block>
+  /**
+   * Used when a {@link PortableTextComponents.block block} component isn't found.
+   */
+  unknownBlock: Component<Block>
+  /**
+   * Component or mapping of components for rendering `list` item type.
+   */
+  list: ComponentOrRecord<List>
+  /**
+   * Used when a {@link PortableTextComponents.list list} component isn't found.
+   */
+  unknownList: Component<List>
+  /**
+   * Component or mapping of components for rendering `list` item type.
+   */
+  listItem: ComponentOrRecord<ListItem>
+  /**
+   * Used when a {@link PortableTextComponents.listItem listItem} component isn't found.
+   */
+  unknownListItem: Component<ListItem>
+  /**
+   * Component or mapping of components for rendering `mark` definition type.
+   */
+  mark: ComponentOrRecord<Mark<never>>
+  /**
+   * Used when a {@link PortableTextComponents.mark mark} component isn't found.
+   */
+  unknownMark: Component<Mark<never>>
+  /**
+   * Component for rendering `spans` of text.
+   * @remarks Added in: `v0.11.0`
+   */
+  text: Component<TextNode>
+  /**
+   * Component for rendering a newline `\n` of text.
+   */
+  hardBreak: Component<TextNode>
+}
+
+/**
+ * Defines how some Portable Text types should be rendered.
+ */
+export type SomePortableTextComponents = Partial<PortableTextComponents>
+
+/**
+ * Component Props
+ *
+ * @typeParam N - Type of Portable Text payload that this component will receive on its `node` property
+ */
+export interface Props<N extends TypedObject> {
+  /**
+   * Portable Text data for this node
+   */
+  node: N
+  /**
+   * Index of the current node within its parent's child list
+   */
+  index: number
+  /**
+   * Indicates whether the node should render as an inline or block element
+   */
+  isInline: boolean
+}
+
+/**
+ * Alias to {@link https://portabletext.github.io/types/interfaces/PortableTextBlock.html PortableTextBlock}
+ * with `style` set to `normal` when undefined
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { Block, Props as $ } from "@portabletext/astro/types";
+ *
+ * type Props = $<Block>;
+ * ---
+ * ```
+ *
+ * @remarks To concisely achieve the same result in the example, use the convenience type {@link BlockProps} instead.
+ */
+export interface Block extends PortableTextBlock {
+  style: 'normal' | PortableTextBlockStyle
+}
+
+/**
+ * Convenience type for {@link Block} component props
+ *
+ * @remarks
+ * Added in: `v0.11.0`
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { BlockProps } from "@portabletext/astro/types";
+ *
+ * type Props = BlockProps;
+ * ---
+ * ```
+ */
+export type BlockProps = Props<Block>
+
+/**
+ * Alias to {@link https://portabletext.github.io/toolkit/types/ToolkitPortableTextList.html ToolkitPortableTextList}
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { List, Props as $ } from "@portabletext/astro/types";
+ *
+ * type Props = $<List>;
+ * ---
+ * ```
+ *
+ * @remarks To concisely achieve the same result in the example, use the convenience type {@link ListProps} instead.
+ */
+export type List = ToolkitPortableTextList
+
+/**
+ * Convenience type for {@link List} component props
+ *
+ * @remarks
+ * Added in: `v0.11.0`
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { ListProps } from "@portabletext/astro/types";
+ *
+ * type Props = ListProps;
+ * ---
+ * ```
+ */
+export type ListProps = Props<List>
+
+/**
+ * Alias to {@link https://portabletext.github.io/toolkit/interfaces/ToolkitPortableTextListItem.html ToolkitPortableTextListItem}
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { ListItem, Props as $ } from "@portabletext/astro/types";
+ *
+ * type Props = $<ListItem>;
+ * ---
+ * ```
+ *
+ * @remarks To concisely achieve the same result in the example, use the convenience type {@link ListItemProps} instead.
+ */
+export type ListItem = ToolkitPortableTextListItem
+
+/**
+ * Convenience type for {@link ListItem} component props
+ *
+ * @remarks
+ * Added in: `v0.11.0`
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { ListItemProps } from "@portabletext/astro/types";
+ *
+ * type Props = ListItemProps;
+ * ---
+ * ```
+ */
+export type ListItemProps = Props<ListItem>
+
+/**
+ * Extends {@link https://portabletext.github.io/toolkit/interfaces/ToolkitNestedPortableTextSpan.html ToolkitNestedPortableTextSpan}
+ * with consisting `markDef` and `markKey` properties
+ *
+ * @typeParam MarkDef - Defines the shape of `markDef` property
+ *
+ * @remarks
+ * To concisely achieve the same result in the example, use the convenience type {@link MarkProps} instead.
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { Mark, Props as $ } from "@portabletext/astro/types";
+ *
+ * type Greet = { msg: string };
+ * type Props = $<Mark<Greet>>;
+ * ---
+ * ```
+ */
+export interface Mark<
+  MarkDef extends Record<string, unknown> | undefined = undefined,
+> extends ToolkitNestedPortableTextSpan {
+  markDef: MarkDef & PortableTextMarkDefinition
+  markKey: string
+}
+
+/**
+ * Convenience type for {@link Mark} component props
+ *
+ * @remarks
+ * Added in: `v0.11.0`
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { MarkProps } from "@portabletext/astro/types";
+ *
+ * type Greet = { msg: string };
+ * type Props = MarkProps<Greet>;
+ * ---
+ * ```
+ */
+export type MarkProps<MarkDef extends Record<string, unknown> | undefined = undefined> = Props<
+  Mark<MarkDef>
+>
+
+/**
+ * Alias to {@link https://portabletext.github.io/toolkit/interfaces/ToolkitTextNode.html ToolkitTextNode}
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { TextNode, Props as $ } from "@portabletext/astro/types";
+ *
+ * type Props = $<TextNode>;
+ * ---
+ * ```
+ *
+ * @remarks To concisely achieve the same result in the example, use the convenience type {@link TextNodeProps} instead.
+ */
+export type TextNode = ToolkitTextNode
+
+/**
+ * Convenience type for {@link TextNode} component props
+ *
+ * @remarks
+ * Added in: `v0.11.0`
+ *
+ * @example
+ * ```ts
+ * ---
+ * import type { TextNodeProps } from "@portabletext/astro/types";
+ *
+ * type Props = TextNodeProps;
+ * ---
+ * ```
+ */
+export type TextNodeProps = Props<TextNode>
+
+/**
+ * The shape of the {@link PortableTextProps.onMissingComponent onMissingComponent} function
+ */
+export type MissingComponentHandler = (
+  message: string,
+  context: {type: string; nodeType: NodeType},
+) => void
+
+/**
+ * Properties for the `RenderHandler` function
+ *
+ * @typeParam T - Type of Portable Text payload
+ * @typeParam Children - Type of children
+ */
+export type RenderHandlerProps<T extends TypedObject = TypedObject, Children = unknown> = {
+  /**
+   * The component that is associated with the Portable Text node.
+   */
+  Component: Component<T>
+  /**
+   * The component props
+   */
+  props: Props<T>
+  /**
+   * The children related to the Portable Text node.
+   * If the node is a custom {@link PortableTextComponents.type type} or a {@link TextNode}, then children will be `undefined`.
+   */
+  children?: Children
+}
+
+/**
+ * The shape of the render component function
+ *
+ * @typeParam T - Type of Portable Text payload
+ * @typeParam Children - Type of children
+ */
+export type RenderHandler<T extends TypedObject = TypedObject, Children = unknown> = (
+  props: RenderHandlerProps<T, Children>,
+) => any
+
+/**
+ * Options for the `render` function accessed via `usePortableText`
+ */
+export type RenderOptions = {
+  type?: RenderHandler<TypedObject, never>
+  block?: RenderHandler<Block>
+  list?: RenderHandler<List>
+  listItem?: RenderHandler<ListItem>
+  mark?: RenderHandler<Mark>
+  text?: RenderHandler<TextNode, never>
+  hardBreak?: RenderHandler<TextNode, never>
+}
+
+/**
+ * Context object returned by `usePortableText`, providing utilities for rendering and customizing Portable Text components.
+ *
+ * The `Context` type includes functions to retrieve default or unknown components and
+ * to customize rendering behavior for specific node types.
+ */
+export interface Context {
+  /**
+   * Retrieves the default `@portabletext/astro` component associated with a Portable Text node.
+   *
+   * @returns The default component for the node, such as `Block`, `List`, etc.
+   *
+   * @example
+   * ```ts
+   * ---
+   * const { getDefaultComponent } = usePortableText(node);
+   * const Component = getDefaultComponent();
+   * ---
+   * <Component {...Astro.props}>
+   *    <slot />
+   * </Component>
+   * ```
+   */
+  getDefaultComponent: () => Component
+  /**
+   * Retrieves the `unknown` component associated with a Portable Text node.
+   *
+   * @returns The component used for unknown nodes, such as `unknownBlock` or `unknownList`.
+   *
+   * @example
+   * ```ts
+   * ---
+   * const { getUnknownComponent } = usePortableText(node);
+   * const Component = getUnknownComponent();
+   * ---
+   * <Component {...Astro.props}>
+   *   <slot />
+   * </Component>
+   * ```
+   */
+  getUnknownComponent: () => Component
+  /**
+   * Customizes rendering for specific Portable Text node types.
+   *
+   * The `render` function enables developers to define custom behavior for specific node types,
+   * such as overriding the default text or mark rendering.
+   *
+   * @remarks
+   * Added in: `v0.11.0`
+   *
+   * @param options {@link RenderOptions} - Configuration for customizing node rendering
+   * @returns The desired output for the Portable Text node
+   *
+   * @example Basic usage
+   * ```ts
+   * ---
+   * import { usePortableText } from "@portabletext/astro";
+   *
+   * const { node } = Astro.props;
+   * const { getDefaultComponent, render } = usePortableText(node);
+   * const Component = getDefaultComponent();
+   * ---
+   * <Component {...Astro.props}>
+   *  {render({
+   *    text: ({ props }) => props.node.text.toUpperCase(),
+   *    mark: ({ Component, props, children }) => (
+   *      <Component {...props} class="custom-mark">{children}</Component>
+   *    ),
+   * </Component>
+   *
+   * <style>
+   *  .custom-mark {
+   *    // some styles
+   *  }
+   * </style>
+   * ```
+   */
+  render: (options: RenderOptions) => any
+}
+
+/**
+ * Generic Portable Text component
+ * @internal
+ */
+export type Component<T extends TypedObject = any> = (props: Props<T>) => any
+
+/**
+ * Defines a component or a mapping of components
+ * @internal
+ */
+export type ComponentOrRecord<T extends TypedObject = any> =
+  | Component<T>
+  | Record<string, Component<T>>
+
+/**
+ * Defines the type of Portable Text node
+ * @internal
+ */
+export type NodeType = 'type' | 'block' | 'list' | 'listItem' | 'mark'

package/lib/utils.d.ts

@@ -0,0 +1,26 @@
+declare module '@portabletext/astro/utils' {
+  /**
+   * @deprecated Use `toPlainText` from `@portabletext/astro` instead
+   */
+  export function toPlainText(
+    ...args: Parameters<typeof import('@portabletext/toolkit').toPlainText>
+  ): ReturnType<typeof import('@portabletext/toolkit').toPlainText>
+  /**
+   * @deprecated Use `spanToPlainText` from `@portabletext/astro` instead
+   */
+  export function spanToPlainText(
+    ...args: Parameters<typeof import('@portabletext/toolkit').spanToPlainText>
+  ): ReturnType<typeof import('@portabletext/toolkit').spanToPlainText>
+  /**
+   * @deprecated Use `mergeComponents` from `@portabletext/astro` instead
+   */
+  export function mergeComponents(
+    ...args: Parameters<typeof import('./utils').mergeComponents>
+  ): ReturnType<typeof import('./utils').mergeComponents>
+  /**
+   * @deprecated Use `usePortableText` from `@portabletext/astro` instead
+   */
+  export function usePortableText(
+    ...args: Parameters<typeof import('./utils').usePortableText>
+  ): ReturnType<typeof import('./utils').usePortableText>
+}

package/lib/utils.ts

@@ -0,0 +1,3 @@
+export {toPlainText, spanToPlainText} from '@portabletext/toolkit'
+export {mergeComponents} from './internal'
+export {usePortableText} from './context'

package/lib/warnings.ts

@@ -0,0 +1,32 @@
+import type {NodeType} from './types'
+
+const getTemplate = (prop: string, type: string): string =>
+  `PortableText [components.${prop}] is missing "${type}"`
+
+export const unknownTypeWarning = (type: string): string => getTemplate('type', type)
+
+export const unknownMarkWarning = (markType: string): string => getTemplate('mark', markType)
+
+export const unknownBlockWarning = (style: string): string => getTemplate('block', style)
+
+export const unknownListWarning = (listItem: string): string => getTemplate('list', listItem)
+
+export const unknownListItemWarning = (listStyle: string): string =>
+  getTemplate('listItem', listStyle)
+
+export const getWarningMessage = (nodeType: NodeType, type: string) => {
+  const fncs = {
+    block: unknownBlockWarning,
+    list: unknownListWarning,
+    listItem: unknownListItemWarning,
+    mark: unknownMarkWarning,
+    type: unknownTypeWarning,
+  }
+
+  return fncs[nodeType](type)
+}
+
+export function printWarning(message: string): void {
+  // oxlint-disable-next-line no-console
+  console.warn(message)
+}

package/package.json

@@ -1,10 +1,92 @@
 {
   "name": "@portabletext/astro",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @portabletext/astro",
+  "version": "0.1.0",
+  "description": "Render Portable Text with Astro",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "astro",
+    "astro-component",
+    "portable-text",
+    "sanity",
+    "withastro"
+  ],
+  "homepage": "https://github.com/portabletext/astro-portabletext#readme",
+  "bugs": {
+    "url": "https://github.com/portabletext/astro-portabletext/issues"
+  },
+  "license": "ISC",
+  "author": "Sanity.io <hello@sanity.io>",
+  "contributors": [
+    "Tom Theisel <tom.theisel@gmail.com> (original author of astro-portabletext)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/portabletext/astro-portabletext.git"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "components",
+    "lib"
+  ],
+  "type": "module",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "lib/*"
+      ]
+    }
+  },
+  "exports": {
+    ".": "./lib/index.ts",
+    "./components": "./lib/components.ts",
+    "./types": "./lib/types.ts",
+    "./utils": {
+      "types": "./lib/utils.d.ts",
+      "import": "./lib/utils.ts",
+      "default": "./lib/utils.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@portabletext/toolkit": "^6.0.0",
+    "@portabletext/types": "^4.0.2"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.1",
+    "@types/leaflet": "^1.9.21",
+    "@types/node": "^26.2.0",
+    "astro": "^7.2.1",
+    "cheerio": "^1.2.0",
+    "leaflet": "^1.9.4",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "rimraf": "^5.0.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "astro": ">=4.6.0"
+  },
+  "lint-staged": {
+    "*": [
+      "oxfmt"
+    ]
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "prebuild:demo": "pnpm clean",
+    "build:demo": "astro build --root demo",
+    "clean": "rimraf demo/dist test/dist",
+    "dev": "astro dev --root demo",
+    "format": "oxfmt .",
+    "lint": "oxlint",
+    "release": "changeset publish",
+    "start": "pnpm dev",
+    "test": "vitest",
+    "type-check": "astro check"
+  }
+}