create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/helpers/conninfo.md

@@ -0,0 +1,112 @@
+# ConnInfo Helper
+
+The ConnInfo Helper helps you to get the connection information. For example, you can get the client's remote address easily.
+
+## Import
+
+Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
+
+**Cloudflare Workers**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/cloudflare-workers'
+```
+
+**Bun**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/bun'
+```
+
+**Vercel**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/vercel'
+```
+
+**AWS Lambda**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/aws-lambda'
+```
+
+**Netlify**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/netlify'
+```
+
+**Lambda@Edge**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/lambda-edge'
+```
+
+**Node.js**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/node-server'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.get('/', (c) => {
+  const info = getConnInfo(c) // info is `ConnInfo`
+  return c.text(`Your remote address is ${info.remote.address}`)
+})
+```
+
+## Type Definitions
+
+The type definitions of the values that you can get from `getConnInfo()` are the following:
+
+```ts
+type AddressType = 'IPv6' | 'IPv4' | undefined
+
+type NetAddrInfo = {
+  /**
+   * Transport protocol type
+   */
+  transport?: 'tcp' | 'udp'
+  /**
+   * Transport port number
+   */
+  port?: number
+
+  address?: string
+  addressType?: AddressType
+} & (
+  | {
+      /**
+       * Host name such as IP Addr
+       */
+      address: string
+
+      /**
+       * Host name type
+       */
+      addressType: AddressType
+    }
+  | {}
+)
+
+/**
+ * HTTP Connection information
+ */
+interface ConnInfo {
+  /**
+   * Remote information
+   */
+  remote: NetAddrInfo
+}
+```

package/docs/framework/helpers/cookie.md

@@ -0,0 +1,232 @@
+# Cookie Helper
+
+The Cookie Helper provides an easy interface to manage cookies, enabling developers to set, parse, and delete cookies seamlessly.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import {
+  deleteCookie,
+  getCookie,
+  getSignedCookie,
+  setCookie,
+  setSignedCookie,
+  generateCookie,
+  generateSignedCookie,
+} from 'acrylblends/cookie'
+```
+
+## Usage
+
+### Regular cookies
+
+```ts
+app.get('/cookie', (c) => {
+  setCookie(c, 'cookie_name', 'cookie_value')
+  const yummyCookie = getCookie(c, 'cookie_name')
+  deleteCookie(c, 'cookie_name')
+  const allCookies = getCookie(c)
+  // ...
+})
+```
+
+### Signed cookies
+
+**NOTE**: Setting and retrieving signed cookies returns a Promise due to the async nature of the WebCrypto API, which is used to create HMAC SHA-256 signatures.
+
+```ts
+app.get('/signed-cookie', (c) => {
+  const secret = 'secret' // make sure it's a large enough string to be secure
+
+  await setSignedCookie(c, 'cookie_name0', 'cookie_value', secret)
+  const fortuneCookie = await getSignedCookie(
+    c,
+    secret,
+    'cookie_name0'
+  )
+  deleteCookie(c, 'cookie_name0')
+  // `getSignedCookie` will return `false` for a specified cookie if its signature fails verification
+  const allSignedCookies = await getSignedCookie(c, secret)
+  // ...
+})
+```
+
+> [!NOTE]
+> `getSignedCookie` distinguishes two cases. A cookie that has a signature but fails verification returns `false`. A cookie that does not have a valid signature format is treated as not being a signed cookie at all and returns `undefined` - the same as when the cookie is not present. This rule applies both when retrieving a single cookie by name and when retrieving all signed cookies. Since both `false` and `undefined` are falsy, `if (!value)` handles both cases.
+
+### Cookie Generation
+
+`generateCookie` and `generateSignedCookie` functions allow you to create cookie strings directly without setting them in the response headers.
+
+#### `generateCookie`
+
+```ts
+// Basic cookie generation
+const cookie = generateCookie('delicious_cookie', 'macha')
+// Returns: 'delicious_cookie=macha; Path=/'
+
+// Cookie with options
+const cookie = generateCookie('delicious_cookie', 'macha', {
+  path: '/',
+  secure: true,
+  httpOnly: true,
+  domain: 'example.com',
+})
+```
+
+#### `generateSignedCookie`
+
+```ts
+// Basic signed cookie generation
+const signedCookie = await generateSignedCookie(
+  'delicious_cookie',
+  'macha',
+  'secret chocolate chips'
+)
+
+// Signed cookie with options
+const signedCookie = await generateSignedCookie(
+  'delicious_cookie',
+  'macha',
+  'secret chocolate chips',
+  {
+    path: '/',
+    secure: true,
+    httpOnly: true,
+  }
+)
+```
+
+**Note**: Unlike `setCookie` and `setSignedCookie`, these functions only generate the cookie strings. You need to manually set them in headers if needed.
+
+## Options
+
+### `setCookie` & `setSignedCookie`
+
+- domain: `string`
+- expires: `Date`
+- httpOnly: `boolean`
+- maxAge: `number`
+- path: `string`
+- secure: `boolean`
+- sameSite: `'Strict'` | `'Lax'` | `'None'`
+- priority: `'Low' | 'Medium' | 'High'`
+- prefix: `secure` | `'host'`
+- partitioned: `boolean`
+
+Example:
+
+```ts
+// Regular cookies
+setCookie(c, 'great_cookie', 'banana', {
+  path: '/',
+  secure: true,
+  domain: 'example.com',
+  httpOnly: true,
+  maxAge: 1000,
+  expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
+  sameSite: 'Strict',
+})
+
+// Signed cookies
+await setSignedCookie(
+  c,
+  'fortune_cookie',
+  'lots-of-money',
+  'secret ingredient',
+  {
+    path: '/',
+    secure: true,
+    domain: 'example.com',
+    httpOnly: true,
+    maxAge: 1000,
+    expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
+    sameSite: 'Strict',
+  }
+)
+```
+
+### `deleteCookie`
+
+- path: `string`
+- secure: `boolean`
+- domain: `string`
+
+Example:
+
+```ts
+deleteCookie(c, 'banana', {
+  path: '/',
+  secure: true,
+  domain: 'example.com',
+})
+```
+
+`deleteCookie` returns the deleted value:
+
+```ts
+const deletedCookie = deleteCookie(c, 'delicious_cookie')
+```
+
+## `__Secure-` and `__Host-` prefix
+
+The Cookie helper supports `__Secure-` and `__Host-` prefixes for cookie names.
+
+If you want to verify if the cookie name has a prefix, specify the prefix option.
+
+```ts
+const securePrefixCookie = getCookie(c, 'yummy_cookie', 'secure')
+const hostPrefixCookie = getCookie(c, 'yummy_cookie', 'host')
+
+const securePrefixSignedCookie = await getSignedCookie(
+  c,
+  secret,
+  'fortune_cookie',
+  'secure'
+)
+const hostPrefixSignedCookie = await getSignedCookie(
+  c,
+  secret,
+  'fortune_cookie',
+  'host'
+)
+```
+
+Also, if you wish to specify a prefix when setting the cookie, specify a value for the prefix option.
+
+```ts
+setCookie(c, 'delicious_cookie', 'macha', {
+  prefix: 'secure', // or `host`
+})
+
+await setSignedCookie(
+  c,
+  'delicious_cookie',
+  'macha',
+  'secret choco chips',
+  {
+    prefix: 'secure', // or `host`
+  }
+)
+```
+
+## Following the best practices
+
+A New Cookie RFC (a.k.a cookie-bis) and CHIPS include some best practices for Cookie settings that developers should follow.
+
+- [RFC6265bis-13](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13)
+  - `Max-Age`/`Expires` limitation
+  - `__Host-`/`__Secure-` prefix limitation
+- [CHIPS-01](https://www.ietf.org/archive/id/draft-cutler-httpbis-partitioned-cookies-01.html)
+  - `Partitioned` limitation
+
+Acryl is following the best practices.
+The cookie helper will throw an `Error` when parsing cookies under the following conditions:
+
+- The cookie name starts with `__Secure-`, but `secure` option is not set.
+- The cookie name starts with `__Host-`, but `secure` option is not set.
+- The cookie name starts with `__Host-`, but `path` is not `/`.
+- The cookie name starts with `__Host-`, but `domain` is set.
+- The `maxAge` option value is greater than 400 days.
+- The `expires` option value is 400 days later than the current time.

package/docs/framework/helpers/css.md

@@ -0,0 +1,285 @@
+# css Helper
+
+> **Not yet available.** The CSS helper (`acrylblends/css`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+The CSS helper - `acrylblends/css` - is Acryl's built-in CSS in JS(X).
+
+You can write CSS in JSX in a JavaScript template literal named `css`. The return value of `css` will be the class name, which is set to the value of the class attribute. The `<Style />` component will then contain the value of the CSS.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { css, cx, keyframes, Style, createCssContext } from 'acrylblends/css'
+```
+
+## `css` *(Experimental)*
+
+You can write CSS in the `css` template literal. In this case, it uses `headerClass` as a value of the `class` attribute. Don't forget to add `<Style />` as it contains the CSS content.
+
+```ts
+app.get('/', (c) => {
+  const headerClass = css`
+    background-color: orange;
+    color: white;
+    padding: 1rem;
+  `
+  return c.html(
+    <html>
+      <head>
+        <Style />
+      </head>
+      <body>
+        <h1 class={headerClass}>Hello!</h1>
+      </body>
+    </html>
+  )
+})
+```
+
+You can style pseudo-classes like `:hover` by using the [nesting selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Nesting_selector), `&`:
+
+```ts
+const buttonClass = css`
+  background-color: #fff;
+  &:hover {
+    background-color: red;
+  }
+`
+```
+
+### Extending
+
+You can extend the CSS definition by embedding the class name.
+
+```tsx
+const baseClass = css`
+  color: white;
+  background-color: blue;
+`
+
+const header1Class = css`
+  ${baseClass}
+  font-size: 3rem;
+`
+
+const header2Class = css`
+  ${baseClass}
+  font-size: 2rem;
+`
+```
+
+In addition, the syntax of `${baseClass} {}` enables nesting classes.
+
+```tsx
+const headerClass = css`
+  color: white;
+  background-color: blue;
+`
+const containerClass = css`
+  ${headerClass} {
+    h1 {
+      font-size: 3rem;
+    }
+  }
+`
+return c.render(
+  <div class={containerClass}>
+    <header class={headerClass}>
+      <h1>Hello!</h1>
+    </header>
+  </div>
+)
+```
+
+### Global styles
+
+A pseudo-selector called `:-acrylblends-global` allows you to define global styles.
+
+```tsx
+const globalClass = css`
+  :-acrylblends-global {
+    html {
+      font-family: Arial, Helvetica, sans-serif;
+    }
+  }
+`
+
+return c.render(
+  <div class={globalClass}>
+    <h1>Hello!</h1>
+    <p>Today is a good day.</p>
+  </div>
+)
+```
+
+Or you can write CSS in the `<Style />` component with the `css` literal.
+
+```tsx
+export const renderer = jsxRenderer(({ children, title }) => {
+  return (
+    <html>
+      <head>
+        <Style>{css`
+          html {
+            font-family: Arial, Helvetica, sans-serif;
+          }
+        `}</Style>
+        <title>{title}</title>
+      </head>
+      <body>
+        <div>{children}</div>
+      </body>
+    </html>
+  )
+})
+```
+
+## `keyframes` *(Experimental)*
+
+You can use `keyframes` to write the contents of `@keyframes`. In this case, `fadeInAnimation` will be the name of the animation.
+
+```tsx
+const fadeInAnimation = keyframes`
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+`
+const headerClass = css`
+  animation-name: ${fadeInAnimation};
+  animation-duration: 2s;
+`
+const Header = () => <a class={headerClass}>Hello!</a>
+```
+
+## `cx` *(Experimental)*
+
+The `cx` composites the two class names.
+
+```tsx
+const buttonClass = css`
+  border-radius: 10px;
+`
+const primaryClass = css`
+  background: orange;
+`
+const Button = () => (
+  <a class={cx(buttonClass, primaryClass)}>Click!</a>
+)
+```
+
+It can also compose simple strings.
+
+```tsx
+const Header = () => <a class={cx('h1', primaryClass)}>Hi</a>
+```
+
+## Usage in combination with [Secure Headers](../middleware/builtin/secure-headers.md) middleware
+
+If you want to use the CSS helpers in combination with the [Secure Headers](../middleware/builtin/secure-headers.md) middleware, you can add the [`nonce` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) to the `<Style nonce={c.get('secureHeadersNonce')} />` to avoid Content-Security-Policy caused by the CSS helpers.
+
+```tsx
+import { secureHeaders, NONCE } from 'acrylblends/secure-headers'
+
+app.get(
+  '*',
+  secureHeaders({
+    contentSecurityPolicy: {
+      // Set the pre-defined nonce value to `styleSrc`:
+      styleSrc: [NONCE],
+    },
+  })
+)
+
+app.get('/', (c) => {
+  const headerClass = css`
+    background-color: orange;
+    color: white;
+    padding: 1rem;
+  `
+  return c.html(
+    <html>
+      <head>
+        {/* Set the `nonce` attribute on the CSS helpers `style` and `script` elements */}
+        <Style nonce={c.get('secureHeadersNonce')} />
+      </head>
+      <body>
+        <h1 class={headerClass}>Hello!</h1>
+      </body>
+    </html>
+  )
+})
+```
+
+## `createCssContext` *(Experimental)*
+
+`createCssContext` creates CSS helper functions (`css`, `cx`, `keyframes`, `viewTransition`, `Style`) with a custom context. You can use it to customize the style element ID and the generated class names.
+
+```ts
+import { createCssContext } from 'acrylblends/css'
+
+const { css, cx, keyframes, Style } = createCssContext({
+  id: 'my-app',
+})
+```
+
+### `classNameSlug`
+
+By default, CSS class names are generated in the format `css-1234567890`. You can customize this by passing a `classNameSlug` function.
+
+The function receives three arguments:
+
+- `hash` - the default generated class name (e.g. `css-1234567890`)
+- `label` - extracted from a `/* comment */` at the start of the CSS template (empty string if none)
+- `css` - the minified CSS string
+
+```ts
+const { css, Style } = createCssContext({
+  id: 'my-styles',
+  classNameSlug: (hash, label) => (label ? `h-${label}` : hash),
+})
+
+const heroClass = css`
+  /* hero-section */
+  background: blue;
+`
+// Generated class name: "h-hero-section"
+```
+
+### `onInvalidSlug`
+
+If the `classNameSlug` function returns an invalid CSS class name, a warning is logged by default. You can customize this behavior with `onInvalidSlug`.
+
+```ts
+const { css, Style } = createCssContext({
+  id: 'my-styles',
+  classNameSlug: (hash, label) => label || hash,
+  onInvalidSlug: (slug) => {
+    throw new Error(`Invalid CSS class name: ${slug}`)
+  },
+})
+```
+
+## Security
+
+The CSS helpers are CSS-authoring APIs: like other CSS-in-JS libraries, interpolated values are inserted as **raw CSS**. They block breaking out into HTML (quotes, backslashes, and `</`), but `{`, `}`, and `;` pass through since they are valid CSS.
+
+**Warning.**
+
+Treat the CSS helpers like other raw sinks (`html`, `raw`, `rawCssString`): **don't pass untrusted input into them directly.** Doing so allows CSS injection. Validate against an allowlist first.
+
+```tsx
+const ALLOWED_COLORS = ['red', 'green', 'blue']
+const color = ALLOWED_COLORS.includes(input) ? input : 'black'
+const headerClass = css`
+  color: ${color};
+`
+```
+
+## Tips
+
+If you use VS Code, you can use [vscode-styled-components](https://marketplace.visualstudio.com/items?itemName=styled-components.vscode-styled-components) for Syntax highlighting and IntelliSense for CSS tagged literals.

package/docs/framework/helpers/dev.md

@@ -0,0 +1,67 @@
+# Dev Helper
+
+> **Not yet available.** The dev helper (`acrylblends/dev`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+Dev Helper provides useful methods you can use in development.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getRouterName, showRoutes } from 'acrylblends/dev'
+```
+
+## `getRouterName()`
+
+You can get the name of the currently used router with `getRouterName()`.
+
+```ts
+const app = new Acryl()
+
+// ...
+
+console.log(getRouterName(app))
+```
+
+## `showRoutes()`
+
+`showRoutes()` function displays the registered routes in your console.
+
+Consider an application like the following:
+
+```ts
+const app = new Acryl().basePath('/v1')
+
+app.get('/posts', (c) => {
+  // ...
+})
+
+app.get('/posts/:id', (c) => {
+  // ...
+})
+
+app.post('/posts', (c) => {
+  // ...
+})
+
+showRoutes(app, {
+  verbose: true,
+})
+```
+
+When this application starts running, the routes will be shown in your console as follows:
+
+```txt
+GET   /v1/posts
+GET   /v1/posts/:id
+POST  /v1/posts
+```
+
+## Options
+
+### *(optional)* verbose: `boolean`
+
+When set to `true`, it displays verbose information.
+
+### *(optional)* colorize: `boolean`
+
+When set to `false`, the output will not be colored.