vercel-labs/json-render

directives

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

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/vercel-labs/json-render --skill directives

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

@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

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills