@highpixel-co/palda-design-system 0.4.1 → 0.5.0

package/dist/scripts/check-examples.mjs

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+/**
+ * 화면 선언서와 시안 마크업을 검사한다.
+ *
+ * 화면은 그리기 전에 본문을 한 문장으로 선언하고, 선언에 들지 않은 것은 곁으로 내린다
+ * (`docs/decisions/0022-screens-declare-their-body.md`). 선언이 산문 규칙으로만 있으면
+ * 화면을 들일 때 빠지기 쉬워서, 셀 수 있는 부분만 검사로 둔다.
+ *
+ * 대상이 둘이다.
+ *
+ * 1. 승인 화면 문서(`examples/approved/*.md`) — 선언서의 항목과 개수.
+ * 2. 시안 HTML(`preview/`·`examples/`의 `.html`) — 같은 선언서 + 바디 블록의 소속 표시.
+ *
+ * 2번은 0022 §적용이 "강제되지 않는 것"에 남겨 둔 곁의 규칙들이다. 당시 근거는 "화면 코드가
+ * 이 저장소에 없어 셀 대상이 없다"였는데, 시안 HTML이 그 대상이다 — 시안 CSS를 `check:css`로
+ * 올린 것과 같은 자리다(`docs/COMPONENT_POLICY.md` §시안은 HTML로 먼저 확정한다).
+ * `AGENTS.md` §항상("반복되는 오류는 검사로 승격한다")을 따른다.
+ *
+ * 실제로 새어 나갔다 — 스토어 알림톡 시안이 결제·구독 요약(명백한 곁)을 `곁: 없음`이라고
+ * 선언해 놓고 `Card` + 행 넷 + 버튼으로 그렸다. 규칙 셋을 전부 어겼는데 선언서만 보는 검사는
+ * 통과했다.
+ *
+ * 곁의 규칙과 별개로 **상태를 누가 드는가**도 한 가지 센다. 행 하나의 실패를 섹션 배너로 올리면
+ * 같은 사실을 두 번 말하고, 면적이 큰 배너가 본문보다 강해진다
+ * (`docs/decisions/0024-state-belongs-to-the-nearest-owner.md`). 스토어 알림톡 시안이 실제로
+ * 그렇게 그려져 목록이 눈에 안 들어왔다.
+ *
+ * 읽지 못하는 것은 그대로 리뷰가 받는다 — 본문 문장의 폭과, 곁이 폭에 밀려 접히는지다. 곁의
+ * 규칙 1(세로로 한 줄)은 마크업으로 이미 갈라 둔 경우만 잡는다. 곁의 자리도 세지 않는다 —
+ * 0022가 자리를 정하지 않고, 본문보다 먼저 오는 것도 규칙 위반이 아니다
+ * (`docs/DESIGN_GRAMMAR.md` §자리는 시스템이 정하지 않는다).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 선언서는 문서 맨 위의 표다. 첫 칸이 항목 이름이고 백틱은 있어도 없어도 된다. */
+const ROW = /^\|([^|]*)\|([^|]*)\|/;
+/** 표의 구분선(`| --- | --- |`)은 항목이 아니다. */
+const DIVIDER = /^[\s:-]*$/;
+
+const PRIMARY_ACTION_PLACES = new Set(['헤더 우측', 'BottomBar']);
+
+/** 시안을 찾는 곳. `preview/`는 untracked라 CI에서는 비어 있고 로컬에서만 걸린다. */
+const SCREEN_DIRS = ['preview', 'examples'];
+
+/** 셸의 바디 밴드. 이 안의 직계 자식이 화면의 블록이다 (`docs/LAYOUT.md` §콘텐츠 세로 순서). */
+const BODY_BAND_CLASS = 'palda-app-shell__band--body';
+
+/** 바디 직계 자식이 밝히는 소속. 순서도 이 순서다 — 헤더 → 본문 → 곁. */
+const ROLE_ATTRIBUTE = /data-screen-role\s*=\s*"([^"]*)"/;
+const ROLES = ['헤더', '본문', '곁'];
+
+/**
+ * 곁이 쓰지 않는 pattern 클래스 (0022 규칙 2 — 본문이 쓰는 pattern을 쓰지 않는다).
+ * 본문이 무엇을 쓰는지와 무관하게 pattern 자체가 "이 화면이 하는 일"을 담는 도구다.
+ * 곁에 남는 표현은 텍스트와 `Link`다(0022 §대가).
+ */
+const BODY_PATTERN_CLASSES = [
+  'palda-card',
+  'palda-form-section',
+  'palda-list-row',
+  'palda-empty-state',
+  'palda-live-preview',
+  'palda-bottom-bar',
+];
+
+/**
+ * 곁이 쓰지 않는 강조 채움 (0022 규칙 3 — 강조 예산은 본문이 갖는다).
+ * 액션의 채움만 본다. 상태 배지는 강조 예산을 쓰지 않는다
+ * (`docs/DESIGN_PRINCIPLES.md` §4의 "상태 색은 이 한도에 들어가지 않는다").
+ */
+const EMPHASIS_CLASSES = [
+  'palda-button--primary',
+  'palda-button--accent',
+  'palda-chip--primary',
+  'palda-chip--accent',
+];
+
+/**
+ * 곁이 세로로 한 줄인지(0022 규칙 1)를 정적으로 근사한다. 블록 요소가 하나라도 들어 있으면
+ * 줄이 나뉜다 — 곁에 남는 표현은 텍스트와 `Link`라(0022 §대가) 인라인만으로 충분하다.
+ * 줄바꿈 자체는 폭에 달려 있어 여전히 못 읽는다. 이 검사가 잡는 것은 마크업으로 이미 갈라 둔
+ * 경우다.
+ */
+const BLOCK_ELEMENTS = new Set([
+  'address',
+  'article',
+  'aside',
+  'blockquote',
+  'div',
+  'dl',
+  'fieldset',
+  'figure',
+  'footer',
+  'form',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'header',
+  'hr',
+  'li',
+  'main',
+  'nav',
+  'ol',
+  'p',
+  'section',
+  'table',
+  'ul',
+]);
+
+/**
+ * 상태를 드는 자리 (0024 — 상태는 가장 가까운 자리가 든다).
+ * 한 섹션이 둘을 같이 쓰면 행 하나의 실패를 섹션이 대신 말한 것이다. `\b`가 `_`를 경계로 보지
+ * 않아 `palda-form-section__error`는 섹션 클래스로 세지 않는다.
+ */
+const FORM_SECTION_CLASS = 'palda-form-section';
+const SECTION_FAILURE_CLASS = 'palda-form-section__error';
+const ROW_FAILURE_CLASS = 'palda-badge--danger';
+
+/** 닫는 태그가 없는 요소. 깊이를 올리지 않는다. */
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+function cell(text) {
+  return text.replace(/`/g, '').trim();
+}
+
+/** 선언서 표의 행을 읽는다. 마크다운이든 HTML 주석 안이든 서식이 같다. */
+function declarationRows(source) {
+  const rows = [];
+  for (const line of source.split('\n')) {
+    const match = ROW.exec(line.trim());
+    if (!match || DIVIDER.test(match[1])) continue;
+    rows.push({ label: cell(match[1]), value: cell(match[2]) });
+  }
+  return rows;
+}
+
+/** 선언서의 셀 수 있는 부분 — 항목이 있는지, 본문이 하나인지, 주 액션 값이 둘 중 하나인지. */
+function checkDeclaration(rows, where, problems) {
+  const body = rows.filter((row) => row.label === '본문');
+  const primary = rows.filter((row) => row.label === '주 액션');
+
+  if (body.length === 0) {
+    problems.push(`${where}: 선언서에 \`본문\` 행이 없다`);
+  } else if (body.length > 1) {
+    problems.push(`${where}: 본문이 ${body.length}개다 — 하나여야 하고, 둘이면 화면을 쪼갠다`);
+  }
+
+  if (primary.length === 0) {
+    problems.push(`${where}: 선언서에 \`주 액션\` 행이 없다`);
+  } else if (primary.length > 1) {
+    problems.push(`${where}: 주 액션이 ${primary.length}개다 — 자리는 하나다`);
+  } else if (!PRIMARY_ACTION_PLACES.has(primary[0].value)) {
+    problems.push(
+      `${where}: 주 액션 자리가 \`${primary[0].value}\`다 — ${[...PRIMARY_ACTION_PLACES]
+        .map((place) => `\`${place}\``)
+        .join(' 또는 ')} 중 하나여야 한다`,
+    );
+  }
+
+  /** `곁` 행에 `없음`이라고 적으면 곁이 0개라는 뜻이다. */
+  const asides = rows
+    .filter((row) => row.label === '곁')
+    .filter((row) => row.value !== '' && row.value !== '없음');
+
+  return { declared: body.length > 0, asides: asides.length };
+}
+
+/** 주석을 같은 길이의 공백으로 지운다. 주석 안의 예시 마크업이 태그로 세지지 않게 한다. */
+function stripComments(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, (match) => ' '.repeat(match.length));
+}
+
+function scanTags(html) {
+  const TAG = /<(\/)?([a-zA-Z][\w-]*)((?:'[^']*'|"[^"]*"|[^'">])*)>/g;
+  const tags = [];
+  let match;
+  while ((match = TAG.exec(html)) !== null) {
+    const attributes = match[3] ?? '';
+    tags.push({
+      closing: match[1] === '/',
+      name: match[2].toLowerCase(),
+      attributes,
+      selfClosing: attributes.trimEnd().endsWith('/'),
+      start: match.index,
+      end: TAG.lastIndex,
+    });
+  }
+  return tags;
+}
+
+/**
+ * 셸 바디 밴드의 직계 자식을 순서대로 돌려준다.
+ * 밴드가 없으면 `null`이다 — 컴포넌트 시안은 화면이 아니라 이 검사를 받지 않는다.
+ */
+function bodyBlocks(html) {
+  const source = stripComments(html);
+  const tags = scanTags(source);
+  const band = tags.findIndex((tag) => !tag.closing && tag.attributes.includes(BODY_BAND_CLASS));
+  if (band < 0) return null;
+
+  const blocks = [];
+  let depth = 0;
+  let open = null;
+
+  for (let index = band + 1; index < tags.length; index += 1) {
+    const tag = tags[index];
+
+    if (tag.closing) {
+      // 밴드 자신이 닫혔다.
+      if (depth === 0) break;
+      depth -= 1;
+      if (depth === 0 && open) {
+        blocks.push({ tag: open, html: source.slice(open.start, tag.end) });
+        open = null;
+      }
+      continue;
+    }
+
+    if (depth === 0) {
+      if (tag.selfClosing || VOID_ELEMENTS.has(tag.name)) {
+        blocks.push({ tag, html: source.slice(tag.start, tag.end) });
+        continue;
+      }
+      open = tag;
+    }
+    if (!tag.selfClosing && !VOID_ELEMENTS.has(tag.name)) depth += 1;
+  }
+
+  return blocks;
+}
+
+/**
+ * 블록 안의 `.palda-form-section` 요소를 HTML 조각으로 하나씩 돌려준다.
+ * 섹션은 중첩되지 않지만, 안쪽 태그의 닫는 순서에 속지 않도록 깊이를 센다.
+ */
+function formSections(html) {
+  const tags = scanTags(html);
+  const sections = [];
+  const isSection = new RegExp(`\\b${FORM_SECTION_CLASS}\\b`);
+
+  for (let index = 0; index < tags.length; index += 1) {
+    const open = tags[index];
+    if (open.closing || !isSection.test(open.attributes)) continue;
+
+    let depth = 0;
+    for (let cursor = index; cursor < tags.length; cursor += 1) {
+      const tag = tags[cursor];
+      if (tag.closing) {
+        depth -= 1;
+        if (depth === 0) {
+          sections.push(html.slice(open.start, tag.end));
+          break;
+        }
+        continue;
+      }
+      if (!tag.selfClosing && !VOID_ELEMENTS.has(tag.name)) depth += 1;
+    }
+  }
+
+  return sections;
+}
+
+/** 바디 블록의 소속 표시와 곁의 규칙을 센다. */
+function checkBlocks(blocks, declaredAsides, where, problems) {
+  const roles = [];
+
+  for (const [index, block] of blocks.entries()) {
+    const match = ROLE_ATTRIBUTE.exec(block.tag.attributes);
+    const role = match ? match[1].trim() : null;
+
+    if (!role) {
+      problems.push(
+        `${where}: 바디 ${index + 1}번째 블록(<${block.tag.name}>)에 data-screen-role이 없다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나를 밝힌다`,
+      );
+      roles.push(null);
+      continue;
+    }
+    if (!ROLES.includes(role)) {
+      problems.push(
+        `${where}: 바디 ${index + 1}번째 블록의 data-screen-role이 \`${role}\`다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나여야 한다`,
+      );
+      roles.push(null);
+      continue;
+    }
+    roles.push(role);
+
+    if (role !== '곁') continue;
+
+    // 규칙 2 — 본문이 쓰는 pattern을 쓰지 않는다.
+    for (const pattern of BODY_PATTERN_CLASSES) {
+      if (new RegExp(`\\b${pattern}\\b`).test(block.html)) {
+        problems.push(
+          `${where}: 곁이 \`${pattern}\`을 쓴다 — 곁은 본문이 쓰는 pattern을 쓰지 않는다 (0022 규칙 2)`,
+        );
+      }
+    }
+
+    // 규칙 3 — 강조 예산을 쓰지 않는다.
+    for (const emphasis of EMPHASIS_CLASSES) {
+      if (new RegExp(`\\b${emphasis}\\b`).test(block.html)) {
+        problems.push(
+          `${where}: 곁이 \`${emphasis}\`를 쓴다 — 강조 예산은 본문이 갖는다 (0022 규칙 3)`,
+        );
+      }
+    }
+
+    // 규칙 1 — 세로로 한 줄이다. 블록 요소가 들어 있으면 이미 여러 줄이다.
+    const inner = scanTags(block.html)
+      .slice(1)
+      .filter((tag) => !tag.closing && BLOCK_ELEMENTS.has(tag.name));
+    if (inner.length > 0) {
+      problems.push(
+        `${where}: 곁 안에 블록 요소(<${inner[0].name}>)가 있다 — 곁은 세로로 한 줄이다 (0022 규칙 1)`,
+      );
+    }
+  }
+
+  // 상태는 가장 가까운 자리가 든다 (0024). 소속과 무관하게 바디 전체를 본다.
+  for (const block of blocks) {
+    for (const section of formSections(block.html)) {
+      if (!section.includes(SECTION_FAILURE_CLASS)) continue;
+      if (!new RegExp(`\\b${ROW_FAILURE_CLASS}\\b`).test(section)) continue;
+      problems.push(
+        `${where}: 한 섹션이 \`${SECTION_FAILURE_CLASS}\` 배너와 \`${ROW_FAILURE_CLASS}\` 배지로 같은 실패를 두 번 말한다 — 행 하나의 실패는 그 행이 든다 (0024)`,
+      );
+    }
+  }
+
+  // 헤더는 하나이고 맨 앞이다 (`docs/LAYOUT.md` §콘텐츠 세로 순서).
+  const headers = roles.filter((role) => role === '헤더').length;
+  if (headers > 1) {
+    problems.push(`${where}: 페이지 헤더가 ${headers}개다 — 하나다`);
+  } else if (headers === 1 && roles[0] !== '헤더') {
+    problems.push(`${where}: 페이지 헤더가 첫 블록이 아니다 — 바디의 맨 위다`);
+  }
+
+  // 본문은 블록 여러 개로 나뉘어도 되지만 사이가 갈리지 않는다. 선언서의 본문은 한 문장이고,
+  // 그 한 문장이 곁을 사이에 두고 두 덩어리로 읽히면 화면이 둘이다.
+  const bodyIndexes = roles.flatMap((role, index) => (role === '본문' ? [index] : []));
+  if (
+    bodyIndexes.length > 1 &&
+    bodyIndexes[bodyIndexes.length - 1] - bodyIndexes[0] + 1 !== bodyIndexes.length
+  ) {
+    problems.push(
+      `${where}: 본문 블록 사이에 다른 것이 끼어 있다 — 본문은 여러 블록이어도 붙어 있어야 한다`,
+    );
+  }
+
+  // 선언되지 않은 곁은 화면에 들어오지 못한다.
+  const drawn = roles.filter((role) => role === '곁').length;
+  if (drawn !== declaredAsides) {
+    problems.push(
+      `${where}: 곁이 선언서에 ${declaredAsides}개인데 화면에 ${drawn}개다 — 적히지 않은 곁은 화면에 들어오지 못한다`,
+    );
+  }
+}
+
+function htmlFiles(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) htmlFiles(full, out);
+    else if (name.endsWith('.html')) out.push(full);
+  }
+  return out;
+}
+
+export function validateScreenHtml(source, where, requireScreen = false) {
+  const problems = [];
+  const blocks = bodyBlocks(source);
+  if (blocks === null) {
+    if (requireScreen) problems.push(`${where}: DS 셸 바디가 없는 HTML은 화면 검사 대상이 아니다`);
+    return problems;
+  }
+  const rows = declarationRows(source);
+  if (rows.length === 0) {
+    problems.push(`${where}: 화면 선언 표가 없다 — 파일 맨 위 주석에 둔다`);
+    return problems;
+  }
+  const { asides } = checkDeclaration(rows, where, problems);
+  checkBlocks(blocks, asides, where, problems);
+  return problems;
+}
+
+export function validateExamples(root = DEFAULT_ROOT) {
+  const problems = [];
+
+  // 1. 승인 화면 문서 — 선언서만 본다. 화면은 시안 HTML이 갖는다.
+  const approvedDir = join(root, 'examples/approved');
+  if (existsSync(approvedDir)) {
+    for (const name of readdirSync(approvedDir)) {
+      if (!name.endsWith('.md') || name === 'README.md') continue;
+      const file = join(approvedDir, name);
+      checkDeclaration(declarationRows(readFileSync(file, 'utf8')), relative(root, file), problems);
+    }
+  }
+
+  // 2. 시안 HTML — 선언서 + 바디 블록의 소속.
+  for (const dir of SCREEN_DIRS) {
+    const full = join(root, dir);
+    if (!existsSync(full)) continue;
+
+    for (const file of htmlFiles(full)) {
+      const source = readFileSync(file, 'utf8');
+      const where = relative(root, file);
+      problems.push(...validateScreenHtml(source, where));
+    }
+  }
+
+  return problems;
+}
+
+function main() {
+  const problems = validateExamples(process.env.DS_ROOT ?? DEFAULT_ROOT);
+  if (problems.length > 0) {
+    console.error(`화면 선언·시안 불일치 ${problems.length}건\n`);
+    for (const problem of problems) console.error(`  ${problem}`);
+    process.exit(1);
+  }
+  console.log('화면 선언·시안 검사 통과');
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highpixel-co/palda-design-system",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Palda product design tokens, icons, React components, and patterns",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,12 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "palda-ds": "./dist/harness/cli.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -32,7 +38,8 @@
       "types": "./dist/tokens.d.ts",
       "import": "./dist/tokens.js"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./catalog": "./dist/harness/metadata.json"
   },
   "sideEffects": [
     "./dist/styles.css"
@@ -52,5 +59,9 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "dependencies": {
+    "js-yaml": "4.3.0",
+    "typescript": "6.0.3"
   }
 }