vercel-labs/json-render

directives

Pre-built custom directives for json-render — formatting, math, string manipulation, and i18n.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/vercel-labs/json-render --skill directives

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

@json-render/directives

Pre-built custom directives for @json-render/core. Drop them into your catalog and renderer to add formatting, math, string manipulation, and i18n.

Quick Start

typescript
import { standardDirectives } from '@json-render/directives';

// Wire into prompt generation
const prompt = catalog.prompt({ directives: standardDirectives });

// Wire into the renderer (React example)
import { JSONUIProvider, Renderer } from '@json-render/react';

<JSONUIProvider registry={registry} directives={standardDirectives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

To add factory directives like createI18nDirective, spread the array:

typescript
import { standardDirectives, createI18nDirective } from '@json-render/directives';

const directives = [...standardDirectives, createI18nDirective(config)];

Defining Custom Directives

Use defineDirective from @json-render/core:

typescript
import { defineDirective, resolvePropValue } from '@json-render/core';
import { z } from 'zod';

const doubleDirective = defineDirective({
  name: '$double',
  description: 'Double a numeric value.',
  schema: z.object({
    $double: z.unknown(),
  }),
  resolve(value, ctx) {
    const resolved = resolvePropValue(value.$double, ctx);
    return (resolved as number) * 2;
  },
});

Rules:

  • Name must start with $
  • Name must not conflict with built-in keys ($state, $cond, $computed, $template, $item, $index, $bindState, $bindItem)
  • Resolvers should call resolvePropValue on sub-values to support composition

Built-in Directives

$format — Locale-aware value formatting

Formats values using Intl formatters. Supports date, currency, number, and percent.

json
{ "$format": "currency", "value": { "$state": "/cart/total" }, "currency": "USD" }
{ "$format": "date", "value": { "$state": "/user/createdAt" } }
{ "$format": "number", "value": 1234567, "notation": "compact" }
{ "$format": "percent", "value": 0.75 }
{ "$format": "date", "value": { "$state": "/post/createdAt" }, "style": "relative" }

Fields: $format (date | currency | number | percent), value (any expression), locale? (string), currency? (string, default "USD"), notation? (string), style? ("relative" for relative dates), options? (extra Intl options).

$math — Arithmetic operations

json
{ "$math": "add", "a": { "$state": "/subtotal" }, "b": { "$state": "/tax" } }
{ "$math": "round", "a": 3.7 }

Operations: add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs. Unary ops (round, floor, ceil, abs) only use a. Division by zero returns 0.

Fields: $math (operation enum), a? (first operand, default 0), b? (second operand, default 0).

$concat — String concatenation

json
{ "$concat": [{ "$state": "/user/firstName" }, " ", { "$state": "/user/lastName" }] }

Fields: $concat (array of values to resolve and join into a string).

$count — Array/string length

json
{ "$count": { "$state": "/cart/items" } }

Returns .length of arrays or strings, 0 for other types.

Fields: $count (value to count).

$truncate — Text truncation

json
{ "$truncate": { "$state": "/post/body" }, "length": 140, "suffix": "..." }

Fields: $truncate (value to truncate), length? (max chars, default 100), suffix? (string, default "...").

$pluralize — Singular/plural forms

json
{ "$pluralize": { "$state": "/cart/itemCount" }, "one": "item", "other": "items", "zero": "no items" }

Output: "3 items", "1 item", or "no items".

Fields: $pluralize (count value), one (singular label), other (plural label), zero? (zero label).

$join — Join array elements

json
{ "$join": { "$state": "/tags" }, "separator": ", " }

Fields: $join (array to join), separator? (string, default ", ").

createI18nDirective — Internationalization factory

typescript
import { createI18nDirective } from '@json-render/directives';

const tDirective = createI18nDirective({
  locale: 'en',
  messages: {
    en: { "greeting": "Hello, {{name}}!", "checkout.submit": "Place Order" },
    es: { "greeting": "Hola, {{name}}!", "checkout.submit": "Realizar Pedido" },
  },
  fallbackLocale: 'en',
});

Usage in specs:

json
{ "$t": "checkout.submit" }
{ "$t": "greeting", "params": { "name": { "$state": "/user/name" } } }

Fields: $t (translation key), params? (interpolation parameters, values accept expressions).

Config: locale (current locale), messages (Record<locale, Record<key, string>>), fallbackLocale? (fallback when key missing).

Composition

Directives compose naturally — each resolver calls resolvePropValue on its inputs, so directives can wrap other directives or built-in expressions:

json
{
  "$format": "currency",
  "value": { "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } },
  "currency": "USD"
}

Resolves inside-out: $state reads from state, $math multiplies, $format formats as currency.

Wiring into Renderers

All four renderers (React, Vue, Svelte, Solid) accept directives on their provider and createRenderer output:

tsx
// Provider pattern
<JSONUIProvider registry={registry} directives={directives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

// createRenderer pattern
const MyRenderer = createRenderer(catalog, components);
<MyRenderer spec={spec} directives={directives} />

For prompt generation, pass the same array:

typescript
const prompt = catalog.prompt({ directives });

Key Exports

ExportPurpose
formatDirective$format directive definition
mathDirective$math directive definition
concatDirective$concat directive definition
countDirective$count directive definition
truncateDirective$truncate directive definition
pluralizeDirective$pluralize directive definition
joinDirective$join directive definition
createI18nDirectiveFactory for $t i18n directive
standardDirectivesArray of all 7 non-factory directives
I18nConfigType for i18n configuration

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills