@portabletext/astro 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @portabletext/astro
+
+## 0.2.0
+
+### Minor Changes
+
+- [#4](https://github.com/portabletext/astro-portabletext/pull/4) [`0fd7cd3`](https://github.com/portabletext/astro-portabletext/commit/0fd7cd372df10919c6ff88d7533f4f7a0293a42e) Thanks [@msfragala](https://github.com/msfragala)! - Allow `PortableText` slots to be scoped to a specific type with `nodeType:type`, e.g. `block:h1`, `mark:link`, `list:bullet`, `listItem:number` and `type:myCustomType`. A scoped slot takes precedence over the node type it belongs to.
+
+  Slots now also take precedence over `render` from `usePortableText`. Previously a component reached through the `components` prop could displace a slot by rendering its children with `render`, so a slot for that node type never applied.
+
+  `Component` is now resolved lazily, so a slot that renders its own markup no longer reports a missing component. This makes a scoped slot enough on its own to render a custom type, which has no default component.
+
+## 0.1.0
+
+### Minor Changes
+
+- [#1](https://github.com/portabletext/astro-portabletext/pull/1) [`e3997e2`](https://github.com/portabletext/astro-portabletext/commit/e3997e216c13cd9da693e924c674cfed52a2d002) Thanks [@stipsan](https://github.com/stipsan)! - Initial release of `@portabletext/astro`, forked from [`astro-portabletext`](https://github.com/theisel/astro-portabletext) by Tom Theisel

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License (ISC)
+
+Copyright 2022 - CURRENT Tom Theisel <tom.theisel@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any 
+purpose with or without fee is hereby granted, provided that the above 
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH 
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND 
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, 
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF 
+THIS SOFTWARE.

package/README.md

@@ -1,45 +1,356 @@
 # @portabletext/astro
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![npm version](https://img.shields.io/npm/v/@portabletext/astro.svg?style=flat-square)](https://www.npmjs.com/package/@portabletext/astro)
+[![npm downloads](https://img.shields.io/npm/dm/@portabletext/astro.svg?style=flat-square)](https://www.npmjs.com/package/@portabletext/astro)
+![license](https://img.shields.io/npm/l/@portabletext/astro?style=flat-square)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Render [Portable Text](https://portabletext.org) with [Astro](https://astro.build).
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+> [!NOTE]
+> This package is a fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext) by [Tom Theisel](https://github.com/theisel), maintained under the [`@portabletext`](https://github.com/portabletext) organization. All credit for the original design and implementation goes to Tom. It remains distributed under the original [ISC License](./LICENSE). See [Migrating from `astro-portabletext`](#migrating-from-astro-portabletext).
 
-## Purpose
+## Table of contents
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@portabletext/astro`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+- [Installation](#installation)
+- [Basic usage](#basic-usage)
+- [Sanity integration](#sanity-integration)
+- [Customizing components](#customizing-components)
+  - [Default components](#default-components)
+  - [Custom components](#custom-components)
+  - [Slots](#slots)
+- [`PortableText` component properties](#portabletext-component-properties)
+- [Utility functions](#utility-functions)
+  - [`usePortableText`](#useportabletext)
+  - [`mergeComponents`](#mergecomponents)
+  - [`toPlainText`](#toplaintext)
+- [Migrating from `astro-portabletext`](#migrating-from-astro-portabletext)
+- [License](#license)
 
-## What is OIDC Trusted Publishing?
+## Installation
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```bash
+npm install @portabletext/astro
+```
 
-## Setup Instructions
+> **Prerequisites:** Astro v4.6 or newer.
 
-To properly configure OIDC trusted publishing for this package:
+## Basic usage
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+Import the `PortableText` component and pass it a Portable Text value. The library provides sensible defaults for rendering all standard Portable Text elements, which you can override.
 
-## DO NOT USE THIS PACKAGE
+```astro
+---
+import {PortableText} from '@portabletext/astro'
+
+const portableText = [
+  {
+    _type: 'block',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', marks: [], text: 'This is a '},
+      {_type: 'span', marks: ['strong'], text: 'bold'},
+      {_type: 'span', marks: [], text: ' text example!'},
+    ],
+  },
+]
+---
+
+<PortableText value={portableText} />
+```
+
+## Sanity integration
+
+This library's predecessor is [officially recommended](https://www.sanity.io/plugins/sanity-astro#rendering-rich-text-and-block-content-with-portable-text) by [Sanity](https://sanity.io) for rendering Portable Text in Astro projects. Helpful resources:
+
+- [Sanity integration for Astro](https://www.sanity.io/plugins/sanity-astro)
+- [Guide: building a blog with Sanity and Astro](https://www.sanity.io/guides/sanity-astro-blog)
+
+## Customizing components
+
+### Default components
+
+Default components are provided for all standard features of the Portable Text spec, with logical HTML defaults. Provided components are merged with the defaults, so you only need to provide the things you want to override.
+
+<details>
+  <summary>View the default structure and output</summary>
+
+```js
+{
+  type: {
+    /* Custom types go here */
+  },
+  block: {
+    h1: /* <h1 {...attrs}><slot /></h1> */,
+    h2: /* <h2 {...attrs}><slot /></h2> */,
+    h3: /* <h3 {...attrs}><slot /></h3> */,
+    h4: /* <h4 {...attrs}><slot /></h4> */,
+    h5: /* <h5 {...attrs}><slot /></h5> */,
+    h6: /* <h6 {...attrs}><slot /></h6> */,
+    blockquote: /* <blockquote {...attrs}><slot /></blockquote> */,
+    normal: /* <p {...attrs}><slot /></p> */
+  },
+  list: {
+    bullet: /* <ul {...attrs}><slot /></ul> */,
+    number: /* <ol {...attrs}><slot /></ol> */,
+    menu: /* <menu {...attrs}><slot /></menu> */,
+  },
+  listItem: {
+    bullet: /* <li {...attrs}><slot /></li> */,
+    number: /* <li {...attrs}><slot /></li> */,
+    menu: /* <li {...attrs}><slot /></li> */,
+  },
+  mark: {
+    code: /* <code {...attrs}><slot /></code> */,
+    em: /* <em {...attrs}><slot /></em> */,
+    link: /* <a {...attrs} href="..."><slot /></a> */,
+    'strike-through': /* <del {...attrs}><slot /></del> */,
+    strong: /* <strong {...attrs}><slot /></strong> */,
+    underline: /* <span {...attrs} style="text-decoration: underline;"><slot /></span> */
+  },
+  text: /* Renders plain text */,
+  hardBreak: /* <br /> */,
+}
+```
+
+</details>
+
+### Custom components
+
+Custom components give you control over how each node is rendered. Map a component to a whole node type, or to a specific property (style, mark type, list item type, etc.) of that node type.
+
+```astro
+---
+import {PortableText} from '@portabletext/astro'
+import Code from '../components/Code.astro'
+import Link from '../components/Link.astro'
+
+const portableText = [
+  // ... your Portable Text content
+]
+
+const components = {
+  // Custom object types, keyed by `_type` (or a single component for all types)
+  type: {code: Code},
+  // Block styles, keyed by `style`
+  block: {/* h1, h2, normal, ... */},
+  // Lists, keyed by `listItem`
+  list: {/* bullet, number, ... */},
+  // List items, keyed by `listItem`
+  listItem: {/* bullet, number, ... */},
+  // Marks (decorators and annotations), keyed by mark type
+  mark: {link: Link},
+  // Fallbacks for unknown nodes
+  unknownType: undefined,
+  unknownBlock: undefined,
+  unknownList: undefined,
+  unknownListItem: undefined,
+  unknownMark: undefined,
+  // Plain text spans and hard breaks
+  text: undefined,
+  hardBreak: undefined,
+}
+---
+
+<PortableText value={portableText} components={components} />
+```
+
+Each custom component receives `node`, `index` and `isInline` props, and renders any children through a `<slot />`. For example, a custom `link` mark:
+
+```astro
+---
+import type {MarkProps} from '@portabletext/astro/types'
+
+export type Props = MarkProps<{href?: string}>
+
+const {node} = Astro.props
+const href = node.markDef?.href
+---
+
+<a href={href}><slot /></a>
+```
+
+### Slots
+
+Slots provide a flexible way to enhance rendering by passing additional props to the resolved component - for example applying custom classes or wrapping elements - without replacing the default component entirely.
+
+```astro
+---
+import {PortableText} from '@portabletext/astro'
+
+const portableText = [
+  // ... your Portable Text content
+]
+---
+
+<PortableText value={portableText}>
+  <fragment slot="mark">
+    {({Component, props, children}) => (
+      <Component {...props} class="mark">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+
+<style>
+  .mark:where(strong) {
+    /* some styles */
+  }
+</style>
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+A slot named after a node type applies to every node of that type: `type`, `block`, `list`, `listItem`, `mark`, `text` and `hardBreak`. To target a single block style, list type, mark type or custom type, scope the slot name with `nodeType:type`.
 
-## More Information
+```astro
+<PortableText value={portableText}>
+  <fragment slot="block:h1">
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="mark:link">
+    {({Component, props, children}) => (
+      <Component {...props} rel="noopener">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="type:callout">
+    {({props}) => <aside class="callout">{props.node.text}</aside>}
+  </fragment>
+</PortableText>
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+A slot only has a `Component` to render when the node type has one. Standard block styles, list types and mark types all ship defaults, but `components.type` starts out empty - a custom type has no default component. So a slot for a custom type either renders its own markup, as `type:callout` does above, or registers a component to receive:
 
+```astro
+<PortableText value={portableText} components={{type: {callout: Callout}}}>
+  <fragment slot="type:callout">
+    {({Component, props}) => <Component {...props} class="callout" />}
+  </fragment>
+</PortableText>
+```
+
+Asking for `Component` when the node type has none gives you the unknown-type component and reports the missing component through [`onMissingComponent`](#portabletext-component-properties). A slot that never touches `Component` renders cleanly.
+
+A scoped slot takes precedence over the node type it belongs to, so `block` can handle every block while `block:h1` handles headings.
+
+```astro
+<PortableText value={portableText}>
+  <!-- Every block except `h1` -->
+  <fragment slot="block">
+    {({Component, props, children}) => (
+      <Component {...props} class="block">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="block:h1">
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
+The `text` and `hardBreak` node types have no types of their own, so they cannot be scoped.
+
+#### Slots and the `components` prop
+
+A slot does not replace the [`components`](#customizing-components) prop, it wraps it. The `Component` handed to a slot is whatever the `components` prop resolved to for that node, so the two compose - the slot decides how the resolved component is rendered.
+
+```astro
+<PortableText value={portableText} components={{block: {h1: MyHeading}}}>
+  <fragment slot="block:h1">
+    <!-- `Component` is `MyHeading` -->
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
+Slots belong to the author of the `PortableText` element, so they always win. A component reached through the `components` prop can customize its own children with [`render`](#useportabletext), but a slot for that node type takes precedence over it.
+
+```astro
+<PortableText value={portableText} components={{block: MyBlock}}>
+  <!-- Applies even if `MyBlock` renders its children with `render({mark: ...})` -->
+  <fragment slot="mark">
+    {({Component, props, children}) => (
+      <Component {...props} class="mark">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
+## `PortableText` component properties
+
+| Property                        | Type                    | Description                                                                                                                                 |
+| ------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                         | `array` or `object`     | Portable Text payload                                                                                                                       |
+| `components` (optional)         | `object`                | Mapping of components to node types or their properties.                                                                                    |
+| `onMissingComponent` (optional) | `function` or `boolean` | Disable warning messages or handle unknown types. **Default** prints to console.                                                            |
+| `listNestingMode` (optional)    | `"html"` or `"direct"`  | List nesting mode. **Default** is `html`. See [ToolkitListNestMode](https://portabletext.github.io/toolkit/types/ToolkitListNestMode.html). |
+
+## Utility functions
+
+```js
+import {usePortableText, mergeComponents, toPlainText, spanToPlainText} from '@portabletext/astro'
+```
+
+### `usePortableText`
+
+Within a component passed into the `components` prop, `usePortableText(node)` returns rendering utilities scoped to that node: `getDefaultComponent()`, `getUnknownComponent()` and `render()`.
+
+```astro
+---
+import type {BlockProps} from '@portabletext/astro/types'
+import {usePortableText} from '@portabletext/astro'
+
+export type Props = BlockProps
+
+const {node} = Astro.props
+const {getDefaultComponent} = usePortableText(node)
+const Default = getDefaultComponent()
+---
+
+<Default {...Astro.props}><slot /></Default>
+```
+
+### `mergeComponents`
+
+Merges two component maps, giving priority to the overrides. Useful for extending a shared base set of components.
+
+```js
+import {mergeComponents} from '@portabletext/astro'
+
+const components = mergeComponents(baseComponents, {
+  block: {h1: MyHeading},
+})
+```
+
+### `toPlainText`
+
+Renders one or more Portable Text blocks as a plain string - handy for meta descriptions or generating slugs. `spanToPlainText` does the same for a single span's children.
+
+```astro
+---
+import {toPlainText} from '@portabletext/astro'
+
+const {node} = Astro.props
+const text = toPlainText(node)
 ---
+```
+
+## Migrating from `astro-portabletext`
+
+`@portabletext/astro` is a drop-in fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext). To migrate, swap the dependency and update your imports:
+
+```diff
+- import {PortableText} from 'astro-portabletext'
++ import {PortableText} from '@portabletext/astro'
+
+- import type {BlockProps} from 'astro-portabletext/types'
++ import type {BlockProps} from '@portabletext/astro/types'
+```
+
+The component API, props and utility functions are unchanged.
+
+## License
 
-**Maintained for OIDC setup purposes only**
+[ISC](./LICENSE) © [Tom Theisel](https://github.com/theisel) (original author) and the Portable Text authors.

package/components/Block.astro

@@ -0,0 +1,36 @@
+---
+import type { Block, Props as $ } from "../lib/types";
+import { usePortableText } from "../lib/utils";
+
+export type Props = $<Block>;
+
+const props = Astro.props;
+const { node, index, isInline, ...attrs } = props;
+const styleIs = (style: string) => style === node.style;
+
+const { getUnknownComponent } = usePortableText(node);
+
+const UnknownStyle = getUnknownComponent();
+---
+
+{
+  styleIs("h1") ? (
+    <h1 {...attrs}><slot /></h1>
+  ) : styleIs("h2") ? (
+    <h2 {...attrs}><slot /></h2>
+  ) : styleIs("h3") ? (
+    <h3 {...attrs}><slot /></h3>
+  ) : styleIs("h4") ? (
+    <h4 {...attrs}><slot /></h4>
+  ) : styleIs("h5") ? (
+    <h5 {...attrs}><slot /></h5>
+  ) : styleIs("h6") ? (
+    <h6 {...attrs}><slot /></h6>
+  ) : styleIs("blockquote") ? (
+    <blockquote {...attrs}><slot /></blockquote>
+  ) : styleIs("normal") ? (
+    <p {...attrs}><slot /></p>
+  ) : (
+    <UnknownStyle {...props}><slot /></UnknownStyle>
+  )
+}

package/components/HardBreak.astro

@@ -0,0 +1,7 @@
+---
+import type { TextNode, Props as $ } from "../lib/types";
+
+export type Props = $<TextNode>;
+---
+
+<br />

package/components/List.astro

@@ -0,0 +1,24 @@
+---
+import type { List, Props as $ } from "../lib/types";
+
+export type Props = $<List>;
+
+const { node, index, isInline, ...attrs } = Astro.props;
+const listItemIs = (listItem: string) => listItem === node.listItem;
+---
+
+{
+  listItemIs("menu") ? (
+    <menu {...attrs}>
+      <slot />
+    </menu>
+  ) : listItemIs("number") ? (
+    <ol {...attrs}>
+      <slot />
+    </ol>
+  ) : (
+    <ul {...attrs}>
+      <slot />
+    </ul>
+  )
+}

package/components/ListItem.astro

@@ -0,0 +1,9 @@
+---
+import type { ListItem, Props as $ } from "../lib/types";
+
+export type Props = $<ListItem>;
+
+const { node, index, isInline, ...attrs } = Astro.props;
+---
+
+<li {...attrs}><slot /></li>

package/components/Mark.astro

@@ -0,0 +1,32 @@
+---
+import type { Mark, Props as $ } from "../lib/types";
+import { usePortableText } from "../lib/utils";
+
+export type Props = $<Mark>;
+
+const props = Astro.props;
+const { node, index, isInline, ...attrs } = props;
+const markTypeIs = (markType: string) => markType === node.markType;
+
+const { getUnknownComponent } = usePortableText(node);
+
+const UnknownMarkType = getUnknownComponent();
+---
+
+{
+  markTypeIs("code") ? (
+    <code {...attrs}><slot /></code>
+  ) : markTypeIs("em") ? (
+    <em {...attrs}><slot /></em>
+  ) : markTypeIs("link") ? (
+    <a href={(node as unknown as Mark<{ href: string }>).markDef.href} {...attrs}><slot /></a>
+  ) : markTypeIs("strike-through") ? (
+    <del {...attrs}><slot /></del>
+  ) : markTypeIs("strong") ? (
+    <strong {...attrs}><slot /></strong>
+  ) : markTypeIs("underline") ? (
+    <span style="text-decoration: underline;" {...attrs}><slot /></span>
+  ) : (
+    <UnknownMarkType {...props}><slot /></UnknownMarkType>
+  )
+}