@portabletext/astro 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @portabletext/astro
+
+## 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,293 @@
 # @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.
 
-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
+```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,
+}
+---
 
-## More Information
+<PortableText value={portableText} components={components} />
+```
 
-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)
+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>
+```
+
+## `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>
+  )
+}