Loads more changes to docs

phlex-ruby · Sep 4, 2024 · d7b1f41 · d7b1f41
1 parent 7c9d9bd
commit d7b1f41
Show file tree

Hide file tree

Showing 18 changed files with 163 additions and 22 deletions.
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
@@ -7,7 +7,7 @@ export default defineConfig({
 		nav: [
 			{ text: "Home", link: "/" },
 			{ text: "Community", link: "project/community" },
-			{ text: "Guide", link: "/guide" },
+			{ text: "Handbook", link: "/handbook" },
 		],
 		sidebar: [
 			{
@@ -18,22 +18,35 @@ export default defineConfig({
 					{ text: "GitHub", link: "https://github.com/phlex-ruby" },
 				],
 			},
+
 			{
-				text: "Guide",
+				text: "Handbook",
+				link: "/handbook/",
 				collapsed: false,
 				items: [
-					{ text: "Intro", link: "/guide/" },
-					{ text: "Setup", link: "/guide/setup" },
-					{ text: "Your first component", link: "/guide/first-component" },
-					{ text: "Under the hood", link: "/guide/under-the-hood" },
-					{ text: "Attributes deep-dive", link: "/guide/attributes" },
-					{ text: "Advanced components", link: "/guide/advanced-components" },
-					{ text: "Tags", link: "/guide/tags" },
-					{ text: "Layouts", link: "/guide/layouts" },
+					{ text: "Intro", link: "/handbook/" },
+					{ text: "Setup", link: "/handbook/setup" },
+					{ text: "Your first component", link: "/handbook/first-component" },
+					{ text: "Under the hood", link: "/handbook/under-the-hood" },
+					{ text: "Attributes deep-dive", link: "/handbook/attributes" },
+					{
+						text: "Advanced components",
+						link: "/handbook/advanced-components",
+					},
+					{ text: "Tags", link: "/handbook/tags" },
+					{ text: "Layouts", link: "/handbook/layouts" },
 				],
 			},
+
+			{
+				text: "Guides",
+				collapsed: false,
+				items: [{ text: "Upgrading to v2", link: "/guides/v2-upgrade" }],
+			},
+
 			{
 				text: "Reference",
+				link: "/reference/",
 				collapsed: false,
 				items: [
 					{ text: "SGML", link: "/reference/sgml" },
@@ -51,16 +64,17 @@ export default defineConfig({
 					},
 				],
 			},
+
 			{
 				text: "Technical Design",
-				collapsed: false,
+				collapsed: true,
 				items: [
 					{ text: "Intro", link: "/design/intro" },
 					{ text: "Caching", link: "/design/caching" },
 					{ text: "Performance", link: "/design/performance" },
-					{ text: "Component Kits" },
-					{ text: "Rails Integration" },
-					{ text: "Selective Rendering" },
+					{ text: "Component kits" },
+					{ text: "Rails integration" },
+					{ text: "Selective rendering" },
 					{ text: "Deferred Render" },
 				],
 			},

diff --git a/design/index.md b/design/index.md
@@ -0,0 +1,3 @@
+# Technical Design
+
+This is a space to go into a little more detail about the technical design of some of the more interesting parts of Phlex. This is worth reading if you’re interested in understanding how Phlex works and maybe considering contributing to the project.
diff --git a/design/intro.md b/design/intro.md
diff --git a/guides/v2-upgrade.md b/guides/v2-upgrade.md
@@ -0,0 +1,33 @@
+# Upgrading to v2
+
+While we’ve tried to keep breaking changes to a minimum, there are a few things you will need to be aware of when upgrading from Phlex v1 to v2.
+
+The latest version of v1 contains a number of deprecations, so we recommend upgrading to the latest version of v1 first.
+
+## Breaking changes
+
+### `template` → `view_template`
+
+Instead of defining the `template` method for your component templates, you should instead define `view_template`.
+
+### `template_tag` → `template`
+
+To render [`<template>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) elements in a `Phlex::HTML` component, you need to call the `template` method instead of the original `template_tag` method.
+
+### We removed `tokens` and `classes`
+
+If you need these back, you can always copy their original implementation from here, paste them into a helper module and include it in your `ApplicationComponent`.
+
+However, we recommend using the new standard capabilities of attributes.
+
+## New features
+
+### Kits
+
+Originally previewed in v1, kits are now out of beta and fully supported in v2. Kits are a way to package up a set of components into a module.
+
+### Selective rendering
+
+### A better cache
+
+Phlex v2 introduces a new attribute cache that caches more things. We wrote about some of the technical details [here](/design/caching).
diff --git a/guide/advanced-components.md → handbook/advanced-components.md b/guide/advanced-components.md → handbook/advanced-components.md
diff --git a/guide/attributes.md → handbook/attributes.md b/guide/attributes.md → handbook/attributes.md
diff --git a/guide/first-component.md → handbook/first-component.md b/guide/first-component.md → handbook/first-component.md
diff --git a/guide/index.md → handbook/index.md b/guide/index.md → handbook/index.md
diff --git a/guide/layouts.md → handbook/layouts.md b/guide/layouts.md → handbook/layouts.md
diff --git a/guide/rails/views.md → handbook/rails/views.md b/guide/rails/views.md → handbook/rails/views.md
diff --git a/guide/setup.md → handbook/setup.md b/guide/setup.md → handbook/setup.md
diff --git a/guide/tags.md → handbook/tags.md b/guide/tags.md → handbook/tags.md
diff --git a/guide/under-the-hood.md → handbook/under-the-hood.md b/guide/under-the-hood.md → handbook/under-the-hood.md
diff --git a/index.md b/index.md
@@ -8,8 +8,11 @@ hero:
   tagline: A little string concatenation library.
   actions:
     - theme: brand
-      text: Guide
-      link: /guide
+      text: Handbook
+      link: /handbook/
+    - theme: alt
+      text: Reference
+      link: /reference/
 
 features:
   - title: Pure, beautiful Ruby

diff --git a/reference/html.md b/reference/html.md
@@ -1 +1,23 @@
-# HTML
+# `Phlex::HTML` < [`Phlex::SGML`](sgml.md)
+
+## Instance methods
+
+We’re not going to list them all here, but `Phlex::HTML` defines an instance method for every non-deprecated HTML element. See the MDN Web Docs for a [complete list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+
+### `#doctype`
+
+This outputs an [HTML5 doctype](https://developer.mozilla.org/en-US/docs/Glossary/Doctype) declaration:
+
+```
+<!doctype html>
+```
+
+### `#svg`
+
+The `#svg` method is special because it yields an instance of [`Phlex::SVG`](svg.md) to the block. This allows you to create SVG content directly in your HTML:
+
+```ruby
+svg do |svg|
+  svg.circle cx: 50, cy: 50, r: 40, fill: "red"
+end
+```
diff --git a/reference/index.md b/reference/index.md
@@ -0,0 +1 @@
+# Reference
diff --git a/reference/sgml.md b/reference/sgml.md
@@ -1 +1,65 @@
-# SGML
+# `Phlex::SGML`
+
+`Phlex::SGML` (which stands for [Standard Generalized Markup Language](https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language)) is the superclass of `Phlex::HTML` and `Phlex::SVG`. It provides a common interface for both HTML and SVG components.
+
+You can use this interface by subclassing either `Phlex::HTML` or `Phlex::SVG` with your own component class.
+
+## Class methods
+
+### `.new`
+
+It’s worth noting that `Phlex::SGML` overrides `.new` in order to capture the block during instantiation. This block will not be passed on to your `#initialize` method. Instead, it is passed to your `#view_template` method when the component is rendered.
+
+### `.register_element`
+
+Allows you to define a custom element that can be used in your templates. Since this defines an instance method, it’s inherited by subclasses.
+
+```ruby{2,5}
+class MyComponent < Phlex::HTML
+  register_element :trix_editor
+
+  def view_template
+    trix_editor
+  end
+end
+```
+
+## Instance methods
+
+### `#after_template`
+
+### `#around_template`
+
+### `#await`
+
+### `#before_template`
+
+### `#call`
+
+### `#capture`
+
+### `#comment`
+
+### `#comment`
+
+### `#context`
+
+### `#flush`
+
+### `#format_object`
+
+### `#plain`
+
+### `#render?`
+
+### `#render`
+
+### `#tag`
+
+### `#unsafe_raw`
+
+### `#unsafe_tag`
+
+### `#vanish`
+
+### `#whitespace`
diff --git a/reference/svg.md b/reference/svg.md
@@ -1 +1,5 @@
-# SVG
+# `Phlex::SVG` < [`Phlex::SGML`](sgml.md)
+
+## Instance methods
+
+We’re not going to list them all here, but `Phlex::SVG` defines an instance method for every non-deprecated SVG element. See the MDN Web Docs for a [complete list](https://developer.mozilla.org/en-US/docs/Web/SVG).