commit 3fa4de2afdb12400baecf8bad81ff37442ebaf3a · nekomimi.pet/atproto-ui

+55 -16

README.md

···

       10
       10
        
       ## Features

     

       11
       11
        
       

     

       12
       12
        
       - Drop-in components for common record types (`BlueskyPost`, `BlueskyProfile`, `TangledString`, etc.).

     

       13
       13
       +
       - Pass prefetched data directly to components to skip API calls—perfect for server-side rendering, caching, or when you already have the data.

     

       13
       14
        
       - Hooks and helpers for composing your own renderers for your own applications, (PRs welcome!)

     

       14
       15
        
       - Built on the lightweight [`@atcute/*`](https://github.com/atcute) clients.

     

       15
       16
        
       

     
···

       39
       40
        
       }

     

       40
       41
        
       ```

     

       41
       42
        
       

     

       43
       43
       +
       ## Passing prefetched data to skip API calls

     

       44
       44
       +
       

     

       45
       45
       +
       All components accept a `record` prop. When provided, the component uses your data immediately without making network requests for that record. This is perfect for SSR, caching strategies, or when you've already fetched data through other means.

     

       46
       46
       +
       

     

       47
       47
       +
       ```tsx

     

       48
       48
       +
       import { BlueskyPost, useLatestRecord } from "atproto-ui";

     

       49
       49
       +
       import type { FeedPostRecord } from "atproto-ui";

     

       50
       50
       +
       

     

       51
       51
       +
       const MyComponent: React.FC<{ did: string }> = ({ did }) => {

     

       52
       52
       +
       	// Fetch the latest post using the hook

     

       53
       53
       +
       	const { record, rkey, loading } = useLatestRecord<FeedPostRecord>(

     

       54
       54
       +
       		did,

     

       55
       55
       +
       		"app.bsky.feed.post"

     

       56
       56
       +
       	);

     

       57
       57
       +
       

     

       58
       58
       +
       	if (loading) return <p>Loading…</p>;

     

       59
       59
       +
       	if (!record || !rkey) return <p>No posts found.</p>;

     

       60
       60
       +
       

     

       61
       61
       +
       	// Pass the fetched record directly—BlueskyPost won't re-fetch it

     

       62
       62
       +
       	return <BlueskyPost did={did} rkey={rkey} record={record} />;

     

       63
       63
       +
       };

     

       64
       64
       +
       ```

     

       65
       65
       +
       

     

       66
       66
       +
       The same pattern works for all components:

     

       67
       67
       +
       

     

       68
       68
       +
       ```tsx

     

       69
       69
       +
       // BlueskyProfile with prefetched data

     

       70
       70
       +
       <BlueskyProfile did={did} record={profileRecord} />

     

       71
       71
       +
       

     

       72
       72
       +
       // TangledString with prefetched data

     

       73
       73
       +
       <TangledString did={did} rkey={rkey} record={stringRecord} />

     

       74
       74
       +
       

     

       75
       75
       +
       // LeafletDocument with prefetched data

     

       76
       76
       +
       <LeafletDocument did={did} rkey={rkey} record={documentRecord} />

     

       77
       77
       +
       ```

     

       78
       78
       +
       

     

       42
       79
        
       ### Available building blocks

     

       43
       80
        
       

     

       44
       81
        
       | Component / Hook                                                | What it does                                                                                                         |

     

       45
       82
        
       | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |

     

       46
       46
       -
       | `AtProtoProvider`                                               | Configures PLC directory (defaults to `https://plc.directory`) and shares protocol clients via React context.        |

     

       47
       47
       -
       | `BlueskyProfile`                                                | Renders a profile card for a DID/handle. Accepts `fallback`, `loadingIndicator`, `renderer`, and `colorScheme`.      |

     

       48
       48
       -
       | `BlueskyPost` / `BlueskyQuotePost`                              | Shows a single Bluesky post, with quotation support, custom renderer overrides, and the same loading/fallback knobs. |

     

       83
       83
       +
       | `AtProtoProvider`                                               | Configures PLC directory (defaults to `https://plc.directory`) and shares protocol clients via React context.                            |

     

       84
       84
       +
       | `AtProtoRecord`                                                 | Core component that fetches and renders any AT Protocol record. **Accepts a `record` prop to use prefetched data and skip API calls.**   |

     

       85
       85
       +
       | `BlueskyProfile`                                                | Renders a profile card for a DID/handle. **Accepts a `record` prop to skip fetching.** Also supports `fallback`, `loadingIndicator`, `renderer`, and `colorScheme`.      |

     

       86
       86
       +
       | `BlueskyPost` / `BlueskyQuotePost`                              | Shows a single Bluesky post with quotation support. **Accepts a `record` prop to skip fetching.** Custom renderer overrides and loading/fallback knobs available. |

     

       49
       87
        
       | `BlueskyPostList`                                               | Lists the latest posts with built-in pagination (defaults: 5 per page, pagination controls on).                      |

     

       50
       50
       -
       | `TangledString`                                                 | Renders a Tangled string (gist-like record) with optional renderer overrides.                                        |

     

       51
       51
       -
       | `LeafletDocument`                                               | Displays long-form Leaflet documents with blocks, theme support, and renderer overrides.                             |

     

       52
       52
       -
       | `useDidResolution`, `useLatestRecord`, `usePaginatedRecords`, … | Hook-level access to records if you want to own the markup or prefill components.                                    |

     

       88
       88
       +
       | `TangledString`                                                 | Renders a Tangled string (gist-like record). **Accepts a `record` prop to skip fetching.** Optional renderer overrides available.                                        |

     

       89
       89
       +
       | `LeafletDocument`                                               | Displays long-form Leaflet documents with blocks and theme support. **Accepts a `record` prop to skip fetching.** Renderer overrides available.                             |

     

       90
       90
       +
       | `useDidResolution`, `useLatestRecord`, `usePaginatedRecords`, … | Hook-level access to records. `useLatestRecord` returns both the `record` and `rkey` so you can pass them directly to components. |

     

       53
       91
        
       

     

       54
       92
        
       All components accept a `colorScheme` of `'light' | 'dark' | 'system'` so they can blend into your design. They also accept `fallback` and `loadingIndicator` props to control what renders before or during network work, and most expose a `renderer` override when you need total control of the final markup.

     

       55
       93
        
       

     

       56
       56
       -
       ### Prefill components with the latest record

     

       94
       94
       +
       ### Using hooks to fetch data once

     

       57
       95
        
       

     

       58
       58
       -
       `useLatestRecord` gives you the most recent record for any collection along with its `rkey`. You can use that key to pre-populate components like `BlueskyPost`, `LeafletDocument`, or `TangledString`.

     

       96
       96
       +
       `useLatestRecord` gives you the most recent record for any collection along with its `rkey`. You can pass both to components to skip the fetch:

     

       59
       97
        
       

     

       60
       98
        
       ```tsx

     

       61
       99
        
       import { useLatestRecord, BlueskyPost } from "atproto-ui";

     

       62
       100
        
       import type { FeedPostRecord } from "atproto-ui";

     

       63
       101
        
       

     

       64
       102
        
       const LatestBlueskyPost: React.FC<{ did: string }> = ({ did }) => {

     

       65
       65
       -
       	const { rkey, loading, error, empty } = useLatestRecord<FeedPostRecord>(

     

       103
       103
       +
       	const { record, rkey, loading, error, empty } = useLatestRecord<FeedPostRecord>(

     

       66
       104
        
       		did,

     

       67
       105
        
       		"app.bsky.feed.post",

     

       68
       106
        
       	);

     

       69
       107
        
       

     

       70
       108
        
       	if (loading) return <p>Fetching latest post…</p>;

     

       71
       109
        
       	if (error) return <p>Could not load: {error.message}</p>;

     

       72
       72
       -
       	if (empty || !rkey) return <p>No posts yet.</p>;

     

       110
       110
       +
       	if (empty || !record || !rkey) return <p>No posts yet.</p>;

     

       73
       111
        
       

     

       74
       74
       -
       	return <BlueskyPost did={did} rkey={rkey} colorScheme="system" />;

     

       112
       112
       +
       	// Pass both record and rkey—no additional API call needed

     

       113
       113
       +
       	return <BlueskyPost did={did} rkey={rkey} record={record} colorScheme="system" />;

     

       75
       114
        
       };

     

       76
       115
        
       ```

     

       77
       116
        
       

     

       78
       78
       -
       The same pattern works for other components: swap the collection NSID and the component you render once you have an `rkey`.

     

       117
       117
       +
       The same pattern works for other components. Just swap the collection NSID and component:

     

       79
       118
        
       

     

       80
       119
        
       ```tsx

     

       81
       120
        
       const LatestLeafletDocument: React.FC<{ did: string }> = ({ did }) => {

     

       82
       82
       -
       	const { rkey } = useLatestRecord(did, "pub.leaflet.document");

     

       83
       83
       -
       	return rkey ? (

     

       84
       84
       -
       		<LeafletDocument did={did} rkey={rkey} colorScheme="light" />

     

       121
       121
       +
       	const { record, rkey } = useLatestRecord(did, "pub.leaflet.document");

     

       122
       122
       +
       	return record && rkey ? (

     

       123
       123
       +
       		<LeafletDocument did={did} rkey={rkey} record={record} colorScheme="light" />

     

       85
       124
        
       	) : null;

     

       86
       125
        
       };

     

       87
       126
        
       ```

     

       88
       127
        
       

     

       89
       128
        
       ## Compose your own component

     

       90
       129
        
       

     

       91
       91
       -
       The helpers let you stitch together custom experiences without reimplementing protocol plumbing. The example below pulls a creator’s latest post and renders a minimal summary:

     

       130
       130
       +
       The helpers let you stitch together custom experiences without reimplementing protocol plumbing. The example below pulls a creator's latest post and renders a minimal summary:

     

       92
       131
        
       

     

       93
       132
        
       ```tsx

     

       94
       133
        
       import { useLatestRecord, useColorScheme, AtProtoRecord } from "atproto-ui";

+19

lib/components/BlueskyPost.tsx

···

       22
       22
        
       	 */

     

       23
       23
        
       	rkey: string;

     

       24
       24
        
       	/**

     

       25
       25
       +
       	 * Prefetched post record. When provided, skips fetching the post from the network.

     

       26
       26
       +
       	 * Note: Profile and avatar data will still be fetched unless a custom renderer is used.

     

       27
       27
       +
       	 */

     

       28
       28
       +
       	record?: FeedPostRecord;

     

       29
       29
       +
       	/**

     

       25
       30
        
       	 * Custom renderer component that receives resolved post data and status flags.

     

       26
       31
        
       	 */

     

       27
       32
        
       	renderer?: React.ComponentType<BlueskyPostRendererInjectedProps>;

     
···

       119
       124
        
       export const BlueskyPost: React.FC<BlueskyPostProps> = ({

     

       120
       125
        
       	did: handleOrDid,

     

       121
       126
        
       	rkey,

     

       127
       127
       +
       	record,

     

       122
       128
        
       	renderer,

     

       123
       129
        
       	fallback,

     

       124
       130
        
       	loadingIndicator,

     
···

       197
       203
        
       		);

     

       198
       204
        
       	}

     

       199
       205
        
       

     

       206
       206
       +
       	// When record is provided, pass it directly to skip fetching

     

       207
       207
       +
       	if (record) {

     

       208
       208
       +
       		return (

     

       209
       209
       +
       			<AtProtoRecord<FeedPostRecord>

     

       210
       210
       +
       				record={record}

     

       211
       211
       +
       				renderer={Wrapped}

     

       212
       212
       +
       				fallback={fallback}

     

       213
       213
       +
       				loadingIndicator={loadingIndicator}

     

       214
       214
       +
       			/>

     

       215
       215
       +
       		);

     

       216
       216
       +
       	}

     

       217
       217
       +
       

     

       218
       218
       +
       	// Otherwise fetch the record using did, collection, and rkey

     

       200
       219
        
       	return (

     

       201
       220
        
       		<AtProtoRecord<FeedPostRecord>

     

       202
       221
        
       			did={repoIdentifier}

+20

lib/components/BlueskyProfile.tsx

···

       17
       17
        
       	did: string;

     

       18
       18
        
       	/**

     

       19
       19
        
       	 * Record key within the profile collection. Typically `'self'`.

     

       20
       20
       +
       	 * Optional when `record` is provided.

     

       20
       21
        
       	 */

     

       21
       22
        
       	rkey?: string;

     

       23
       23
       +
       	/**

     

       24
       24
       +
       	 * Prefetched profile record. When provided, skips fetching the profile from the network.

     

       25
       25
       +
       	 */

     

       26
       26
       +
       	record?: ProfileRecord;

     

       22
       27
        
       	/**

     

       23
       28
        
       	 * Optional renderer override for custom presentation.

     

       24
       29
        
       	 */

     
···

       94
       99
        
       export const BlueskyProfile: React.FC<BlueskyProfileProps> = ({

     

       95
       100
        
       	did: handleOrDid,

     

       96
       101
        
       	rkey = "self",

     

       102
       102
       +
       	record,

     

       97
       103
        
       	renderer,

     

       98
       104
        
       	fallback,

     

       99
       105
        
       	loadingIndicator,

     
···

       128
       134
        
       			/>

     

       129
       135
        
       		);

     

       130
       136
        
       	};

     

       137
       137
       +
       

     

       138
       138
       +
       	// When record is provided, pass it directly to skip fetching

     

       139
       139
       +
       	if (record) {

     

       140
       140
       +
       		return (

     

       141
       141
       +
       			<AtProtoRecord<ProfileRecord>

     

       142
       142
       +
       				record={record}

     

       143
       143
       +
       				renderer={Wrapped}

     

       144
       144
       +
       				fallback={fallback}

     

       145
       145
       +
       				loadingIndicator={loadingIndicator}

     

       146
       146
       +
       			/>

     

       147
       147
       +
       		);

     

       148
       148
       +
       	}

     

       149
       149
       +
       

     

       150
       150
       +
       	// Otherwise fetch the record using did, collection, and rkey

     

       131
       151
        
       	return (

     

       132
       152
        
       		<AtProtoRecord<ProfileRecord>

     

       133
       153
        
       			did={repoIdentifier}

+18

lib/components/LeafletDocument.tsx

···

       30
       30
        
       	 */

     

       31
       31
        
       	rkey: string;

     

       32
       32
        
       	/**

     

       33
       33
       +
       	 * Prefetched Leaflet document record. When provided, skips fetching from the network.

     

       34
       34
       +
       	 */

     

       35
       35
       +
       	record?: LeafletDocumentRecord;

     

       36
       36
       +
       	/**

     

       33
       37
        
       	 * Optional custom renderer for advanced layouts.

     

       34
       38
        
       	 */

     

       35
       39
        
       	renderer?: React.ComponentType<LeafletDocumentRendererInjectedProps>;

     
···

       70
       74
        
       export const LeafletDocument: React.FC<LeafletDocumentProps> = ({

     

       71
       75
        
       	did,

     

       72
       76
        
       	rkey,

     

       77
       77
       +
       	record,

     

       73
       78
        
       	renderer,

     

       74
       79
        
       	fallback,

     

       75
       80
        
       	loadingIndicator,

     
···

       116
       121
        
       		);

     

       117
       122
        
       	};

     

       118
       123
        
       

     

       124
       124
       +
       	// When record is provided, pass it directly to skip fetching

     

       125
       125
       +
       	if (record) {

     

       126
       126
       +
       		return (

     

       127
       127
       +
       			<AtProtoRecord<LeafletDocumentRecord>

     

       128
       128
       +
       				record={record}

     

       129
       129
       +
       				renderer={Wrapped}

     

       130
       130
       +
       				fallback={fallback}

     

       131
       131
       +
       				loadingIndicator={loadingIndicator}

     

       132
       132
       +
       			/>

     

       133
       133
       +
       		);

     

       134
       134
       +
       	}

     

       135
       135
       +
       

     

       136
       136
       +
       	// Otherwise fetch the record using did, collection, and rkey

     

       119
       137
        
       	return (

     

       120
       138
        
       		<AtProtoRecord<LeafletDocumentRecord>

     

       121
       139
        
       			did={did}

+17

lib/components/TangledString.tsx

···

       11
       11
        
       	did: string;

     

       12
       12
        
       	/** Record key within the `sh.tangled.string` collection. */

     

       13
       13
        
       	rkey: string;

     

       14
       14
       +
       	/** Prefetched Tangled String record. When provided, skips fetching from the network. */

     

       15
       15
       +
       	record?: TangledStringRecord;

     

       14
       16
        
       	/** Optional renderer override for custom presentation. */

     

       15
       17
        
       	renderer?: React.ComponentType<TangledStringRendererInjectedProps>;

     

       16
       18
        
       	/** Fallback node displayed before loading begins. */

     
···

       58
       60
        
       export const TangledString: React.FC<TangledStringProps> = ({

     

       59
       61
        
       	did,

     

       60
       62
        
       	rkey,

     

       63
       63
       +
       	record,

     

       61
       64
        
       	renderer,

     

       62
       65
        
       	fallback,

     

       63
       66
        
       	loadingIndicator,

     
···

       78
       81
        
       			canonicalUrl={`https://tangled.org/strings/${did}/${encodeURIComponent(rkey)}`}

     

       79
       82
        
       		/>

     

       80
       83
        
       	);

     

       84
       84
       +
       

     

       85
       85
       +
       	// When record is provided, pass it directly to skip fetching

     

       86
       86
       +
       	if (record) {

     

       87
       87
       +
       		return (

     

       88
       88
       +
       			<AtProtoRecord<TangledStringRecord>

     

       89
       89
       +
       				record={record}

     

       90
       90
       +
       				renderer={Wrapped}

     

       91
       91
       +
       				fallback={fallback}

     

       92
       92
       +
       				loadingIndicator={loadingIndicator}

     

       93
       93
       +
       			/>

     

       94
       94
       +
       		);

     

       95
       95
       +
       	}

     

       96
       96
       +
       

     

       97
       97
       +
       	// Otherwise fetch the record using did, collection, and rkey

     

       81
       98
        
       	return (

     

       82
       99
        
       		<AtProtoRecord<TangledStringRecord>

     

       83
       100
        
       			did={did}