Add docs

.gitattributes

@@ -1,5 +1,7 @@
 /bin/ export-ignore
 /build/ export-ignore
+/docs/ export-ignore
+/docs-src/ export-ignore
 /src/Block.php linguist-generated
 /src/Codepoint.php linguist-generated
 /src/Codepoint/*.php linguist-generated

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ on:
       - main
   repository_dispatch:
     types:
-      - ci
+      - tests
 
 jobs:
   ci:
@@ -70,3 +70,41 @@ jobs:
       -
         name: PHPUnit
         run: composer run-script test -- --colors=always
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: docs-src/package-lock.json
+      -
+        name: Install NPM dependencies
+        run: cd docs-src && npm ci
+      -
+        name: Check coding style
+        run: cd docs-src && npm run-script lint
+      -
+        name: Build
+        run: cd docs-src && npm run-script build
+      -
+        name: Check changes
+        id: check-changes
+        if: github.repository == 'mlocati/unipoints' && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+            if git diff --exit-code --name-status; then
+                echo "commit=yes" >>"$GITHUB_OUTPUT"
+            fi
+      -
+        name: Push changes
+        if: steps.check-changes.outputs.commit == 'yes'
+        run: |
+            git add --all
+            git commit -m 'Rebuilding docs'
+            git push

bin/unipoints

@@ -10,7 +10,11 @@ use MLUnipoints\Build\DataStorage;
 use MLUnipoints\Build\Filesystem;
 use MLUnipoints\Build\UserMessageException;
 use MLUnipoints\Codepoint;
+use MLUnipoints\Info\BlockInfo;
+use MLUnipoints\Info\CodepointInfo;
+use MLUnipoints\Info\PlaneInfo;
 use MLUnipoints\Info\UnicodeInfo;
+use MLUnipoints\Plane;
 
 const DEFAULT_VERSION = '15.1.0';
 
@@ -54,15 +58,16 @@ function showSyntax(string $name): void
 {
     $defaultVersion = DEFAULT_VERSION;
     echo <<<EOT
-Syntax {$name} <-h|--help|installed|latest|check-newer|build [version]>
+Syntax {$name} <-h|--help|installed|latest|check-newer|build [version]|docs [--pretty]>
 
 Where:
 - installed: print the Unicode version used to build the data in this project
 - latest: print the latest version of Unicode
 - check-newer: check if the latest Unicode version is greater than the installed one
 - build [version]: (re) build the data in this project.
   If [version] is not specified, we'll install version {$defaultVersion}
-
+- docs: generate the data for the docs
+  Use the --pretty option to build pretty/unminified data
 EOT
     ;
 }
@@ -127,9 +132,120 @@ function build(string $unicodeVersion): int
     $codepointsBuilder = new CodepointsBuilder(unicodeVersion: $unicodeVersion, blocksBuilder: $blocksBuilder);
     $codepointsBuilder->saveAllCodepoints();
     echo "done.\n";
+
+    return generateDocs(false);
+}
+
+function generateDocs(bool $pretty): int
+{
+    echo $pretty ? "Generating pretty data for the docs\n" : "Generating data for the docs\n";
+    echo '- collecting data... ';
+    $planes = [];
+    foreach (Plane::cases() as $plane) {
+        $planes[] = generatePlaneDocs($plane);
+    }
+    $data = [
+        'unicodeVersion' => getInstalledUnicodeVersion(),
+        'planes' => $planes,
+    ];
+    $json = json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS | ($pretty ? JSON_PRETTY_PRINT : 0));
+    echo "done.\n";
+    foreach ([
+        'docs/assets/data.json',
+        'docs-src/public/assets/data.json',
+    ] as $relFile) {
+        echo "- saving {$relFile}... ";
+        $file = __DIR__ . '/../' . $relFile;
+        $dir = dirname($file);
+        if (!is_dir($dir)) {
+            if (!mkdir($dir, 0777, true)) {
+                throw new RuntimeException('Failed to create output directory');
+            }
+        }
+        if (file_put_contents($file, $json) !== strlen($json)) {
+            throw new RuntimeException('Failed to create data.json');
+        }
+        echo "done.\n";
+    }
     return 0;
 }
 
+function generatePlaneDocs(Plane $plane): array
+{
+    $planeInfo = PlaneInfo::from($plane);
+    $blocks = [];
+    foreach (Block::cases() as $block) {
+        $blockInfo = BlockInfo::from($block);
+        if ($blockInfo->plane === $plane) {
+            $blocks[] = generateBlockDocs($block);
+        }
+    }
+
+    return [
+        'id' => $plane->value,
+        'unassigned' => $planeInfo->unassigned,
+        'name' => $planeInfo->name,
+        'shortName' => $planeInfo->shortName,
+        'fromCodepoint' => $planeInfo->fromCodepoint,
+        'toCodepoint' => $planeInfo->toCodepoint,
+        'blocks' => $blocks,
+    ];
+}
+
+function generateBlockDocs(Block $block): array
+{
+    $blockInfo = BlockInfo::from($block);
+    $codepoints = [];
+    $codepointsClassName = 'MLUnipoints\\Codepoint\\' . $blockInfo->codename;
+    if (stripos($codepointsClassName, 'surrogate') === false || enum_exists($codepointsClassName)) {
+        $codepointsClass = new ReflectionEnum($codepointsClassName);
+        foreach ($codepointsClass->getCases() as $codepoint) {
+            $codepoints[] = generateCodepointDocs($codepoint->getValue());
+        }
+    }
+
+    return [
+        'name' => $blockInfo->name,
+        'codename' => $blockInfo->codename,
+        'fromCodepoint' => $blockInfo->fromCodepoint,
+        'toCodepoint' => $blockInfo->toCodepoint,
+        'codepoints' => $codepoints,
+    ];
+}
+
+function generateCodepointDocs(BackedEnum $codepoint): array
+{
+    $info = CodepointInfo::from($codepoint);
+    $result = [
+        'id' => $info->id,
+        'name' => $info->name,
+        'codename' => $codepoint->name,
+        'char' => $codepoint->value,
+    ];
+    foreach ([
+        'unicode1Name',
+    ] as $prop) {
+        if ($info->{$prop} !== '') {
+            $result[$prop] = $info->{$prop};
+        }
+    }
+    foreach ([
+        'formalAliases',
+        'informativeAliases',
+        'correctedNames',
+        'controlNames',
+        'alternateNames',
+        'figments',
+        'abbreviations',
+    ] as $prop) {
+        if ($info->{$prop} !== []) {
+            $result[$prop] = $info->{$prop};
+        }
+    }
+
+    return $result;
+}
+
 function main(array $args): int
 {
     if (array_intersect(['-h', '--help'], $args) !== []) {
@@ -165,6 +281,19 @@ function main(array $args): int
             }
             showSyntax($args[0]);
             return 1;
+        case 'docs':
+            switch ($numArgs) {
+                case 2:
+                    return generateDocs(false);
+                case 3:
+                    if ($args[2] !== '--pretty') {
+                        showSyntax($args[0]);
+                        return 1;
+                    }
+                    return generateDocs(true);
+            }
+            showSyntax($args[0]);
+            return 1;
     }
     showSyntax($args[0]);
     return 1;

docs-src/.eslintrc.cjs

@@ -0,0 +1,15 @@
+/* eslint-env node */
+require('@rushstack/eslint-patch/modern-module-resolution')
+
+module.exports = {
+  root: true,
+  extends: [
+    'plugin:vue/vue3-essential',
+    'eslint:recommended',
+    '@vue/eslint-config-typescript',
+    '@vue/eslint-config-prettier/skip-formatting'
+  ],
+  parserOptions: {
+    ecmaVersion: 'latest'
+  }
+}

docs-src/.gitignore

@@ -0,0 +1,26 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+coverage
+*.local
+
+/cypress/videos/
+/cypress/screenshots/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

docs-src/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "semi": false,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "none"
+}

docs-src/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "Vue.vscode-typescript-vue-plugin",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode"
+  ]
+}

docs-src/README.md

@@ -0,0 +1,40 @@
+# Web Interface
+
+## Recommended IDE Setup
+
+[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+
+## Type Support for `.vue` Imports in TS
+
+TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
+
+If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
+
+1. Disable the built-in TypeScript Extension
+    1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette
+    2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
+2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
+
+## Project Setup
+
+```sh
+npm ci
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Type-Check, Compile and Minify for Production
+
+```sh
+npm run build
+```
+
+### Lint with [ESLint](https://eslint.org/)
+
+```sh
+npm run lint
+```

docs-src/components.d.ts

@@ -0,0 +1,18 @@
+/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// Generated by unplugin-vue-components
+// Read more: https://github.com/vuejs/core/pull/3399
+export {}
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    BlockViewer: typeof import('./src/components/DataViewer/BlockViewer.vue')['default']
+    CodepointViewer: typeof import('./src/components/DataViewer/CodepointViewer.vue')['default']
+    CopiableText: typeof import('./src/components/CopiableText.vue')['default']
+    DataFilter: typeof import('./src/components/DataFilter.vue')['default']
+    DataViewer: typeof import('./src/components/DataViewer.vue')['default']
+    HeaderElement: typeof import('./src/components/HeaderElement.vue')['default']
+    PlaneViewer: typeof import('./src/components/DataViewer/PlaneViewer.vue')['default']
+  }
+}

docs-src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

docs-src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Unipoints</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>