Update module repos and generate docs; Improve organization of modules

Author: eliot-akira

docs/pages/projects/blocks/index.md docs/pages/modules/blocks/index.mddocs/pages/projects/blocks/index.md renamed to docs/pages/modules/blocks/index.md

@@ -10,7 +10,7 @@ A command-line tool to quickly set up new projects based on templates.
 
 ## Usage
 
-Prerequisites: Git and Node.js 18 or above
+Prerequisites: Linux, macOS, or [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/about); [Git](https://git-scm.com/), [Node](https://nodejs.org/en/) (version 20 and above)
 
 Run the tool to create a new project.
 

docs/pages/projects/create/index.md docs/pages/modules/create/index.mddocs/pages/projects/create/index.md renamed to docs/pages/modules/create/index.md

@@ -4,32 +4,36 @@ title: Design
 <!--
 Do not edit this file - Generated from https://github.com/tangibleinc/design
 -->
-# Design
+# Design Library
 
-The Design library includes themeable user interface components, design tokens, and styling utilities. It is written in Sass and TypeScript with React.
+The Design Library includes unstyled and themeable user interface components, patterns, design tokens, and styling utilities for creating a design system. It is available as CSS/Sass, JSON/JavaScript/TypeScript, and React.
 
-**Status: Draft**
+Website: https://design.tangible.one
+
+Repository: https://github.com/tangibleinc/design
+
+**Status: Draft** - Currently in research phase
 
 ## Getting started
 
 Prerequisites: [Node](https://nodejs.org/) or [Bun](https://bun.sh/)
 
-Install as dev dependency.
+Install as dependency.
 
 ```sh
-npm install -D @tangible/design
+npm install @tangible/ui
 ```
 
 ### Sass
 
 ```scss
-@import "@tangible/design";
+@import "@tangible/ui";
 ```
 
 ### TypeScript
 
 ```ts
-import * as design from '@tangible/design'
+import * as ui from '@tangible/ui'
 ```
 
 

docs/pages/projects/design/index.md docs/pages/modules/design/index.mddocs/pages/projects/design/index.md renamed to docs/pages/modules/design/index.md

@@ -146,15 +146,15 @@ https://docs.phpunit.de/en/9.6/ for more information.
 
 #### Method 2: Using wp-env (Recommended)
 
-Alternatively, you can use the [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) tool to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions.
+Alternatively, you can use the [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) tool to serve local dev and test sites, optionally switching between multiple PHP versions.
 
 The test environment is started by running:
 
 ```sh
 npm run env:start
 ```
 
-This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions. `wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
+This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/), which requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
 
 Visit [http://localhost:8888](http://localhost:8888) to see the dev site, and [http://localhost:8889](http://localhost:8880) for the test site, whose database is cleared on every run.
 

docs/pages/projects/docs.md docs/pages/modules/docs.mddocs/pages/projects/docs.md renamed to docs/pages/modules/docs.md

@@ -4,11 +4,19 @@ title: Design
 <!--
 Do not edit this file - Generated from https://github.com/tangibleinc/framework
 -->
-# Integrate Design library with WordPress
+# Design library
 
-In the Framework, it would be convenient to bundle the library `@tangible/design`, made of Sass and JavaScript, into independently loadable modules under a shared global namespace.
+This is a set of design styles, components, and assets and for use by Tangible plugins.
 
-- `design-core.min.css`
-- `design-core.min.js`
-- `design-component.*.min.css`
-- `design-component.*.min.js`
+## Plan
+
+Integrate the general-purpose design library with curated tokens and CSS variables.
+
+- `core.min.css`
+  - class `t-design`
+- `core.min.js`
+  - `Tangible.Design`
+- `component.*.min.css`
+  - class `t-Component`
+- `component.*.min.js`
+  - class `Component` exported from `@tangible/design`

docs/pages/modules/fields/index.md

@@ -4,6 +4,6 @@ title: Env
 <!--
 Do not edit this file - Generated from https://github.com/tangibleinc/framework
 -->
-# @tangible/env
+# Env
 
 Local dev and test environment setup with WordPress Playground and Playwright

docs/pages/modules/framework/design/index.md

@@ -14,6 +14,75 @@ Many of these were refactored from the deprecated [plugin framework v2](https://
 
 Git repository: https://github.com/tangibleinc/framework
 
+## Install
+
+Add as a production dependency in `tangible.config.js`.
+
+```js
+export default {
+  install: [
+    {
+      git: 'git@github.com:tangibleinc/framework',
+      dest: 'vendor/tangible/framework',
+      branch: 'main',
+    },
+  ]
+}
+```
+
+Run `npm run install` or `npx roll install`.
+
+Alternatively, add in `composer.json` and run `composer update`.
+
+```json
+{
+  "repositories": [
+    {
+      "type": "vcs",
+      "url": "git@github.com:tangibleinc/framework"
+    }
+  ],
+  "require": {
+    "tangible/framework": "dev-main"
+  },
+  "minimum-stability": "dev"
+}
+```
+
+## Use
+
+After loading the framework, its newest version instance is ready on `plugins_loaded` action.
+
+```php
+use tangible\framework;
+
+require_once __DIR__ . '/vendor/tangible/framework/index.php';
+
+add_action('plugins_loaded', function() {
+
+  // Newest version of Framework is ready
+
+});
+```
+
+### Note on plugin activation
+
+During plugin activation, such as after install or update, WordPress runs the `plugins_loaded` action *before* loading plugins and modules, short-circuiting the version comparison logic. This can cause an older version of a module to load with missing features.
+
+It is recommended to check for the constant `WP_SANDBOX_SCRAPING`, and skip loading the rest of the plugin when it's defined.
+
+```php
+if (defined('WP_SANDBOX_SCRAPING')) return;
+
+// ..Register with Framework and load the rest of plugin..
+```
+
+This guarantees the availability of the newest version of all modules. For more details, see:
+
+- https://developer.wordpress.org/reference/functions/register_activation_hook/#more-information
+- https://github.com/WordPress/wordpress-develop/blob/8a52d746e9bb85604f6a309a87d22296ce1c4280/src/wp-admin/includes/plugin.php#L2381C10-L2381C31
+
+
 ## Modules
 
 - [Admin](admin)
@@ -91,7 +160,7 @@ npm run format [module1 module2..]
 Start a local dev site using [`wp-now`](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md).
 
 ```sh
-npm run start
+npm run now
 ```
 
 Press CTRL + C to stop.
@@ -131,40 +200,40 @@ This plugin comes with a suite of unit and integration tests.
 The test environment is started by running:
 
 ```sh
-npm run env:start
+npm run start
 ```
 
-This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions. It requires **Docker** to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
+This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) to set up a local dev and test site, optionally switching between multiple PHP versions. It requires **Docker** to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
 
 Visit [http://localhost:8888](http://localhost:8888) to see the dev site, and [http://localhost:8889](http://localhost:8880) for the test site, whose database is cleared on every run.
 
 Before running tests, install PHPUnit as a dev dependency using Composer inside the container.
 
 ```sh
-npm run env:composer:install
+npm run composer:install
 ```
 
 Composer will add and remove folders in the `vendor` folder, based on `composer.json` and `composer.lock`. If you have any existing Git repositories, ensure they don't have any work in progress before running the above command.
 
 Run the tests:
 
 ```sh
-npm run env:test
+npm run test
 ```
 
 For each PHP version:
 
 ```sh
-npm run env:test:7.4
-npm run env:test:8.2
+npm run test:7.4
+npm run test:8.2
 ```
 
 The version-specific commands take a while to start, but afterwards you can run `npm run env:test` to re-run tests in the same environment.
 
 To stop the Docker process:
 
 ```sh
-npm run env:stop
+npm run stop
 ```
 
 To remove Docker containers, volumes, images associated with the test environment.

docs/pages/modules/framework/env/index.md

@@ -4,8 +4,8 @@ title: Now
 <!--
 Do not edit this file - Generated from https://github.com/tangibleinc/now
 -->
-# @tangible/now
+# Now
 
-> Standalone command-line tool to manage local WordPress sites
+> Standalone command-line tool to run local sites on WordPress Playground
 
 This is a fork of [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now), customized for local development and testing purpose.