Merge pull request #423 from Automattic/trunk

Alpha release Mar 05

Author: rbcorrales

.github/UTILITY_CLASSES.md

@@ -1,26 +1,3 @@
-# Newspack Grid
-
-Adding `newspack-grid` or `newspack-grid-small` to a Columns block ensures the columns fit on the grid on large screens.
-
-`newspack-grid` is designed for use with a wide Columns block. It supports the following layouts:
-
-- 25% / 50% / 25%
-- 33.33% / 33.33% / 33.33%
-- 15% / 70% / 15%
-- 66.66% / 33.33% or 33.33% / 66.66%
-
-_Note: These layouts are also available as patterns._
-
-`newspack-grid-small` is for narrow columns (e.g., at 632px) and currently supports only one layout type: 66.66% / 33.33% or 33.33% / 66.66%.
-
-For a single sidebar layout, you need to apply both the `newspack-grid` and `newspack-grid--sidebar` classes. The `newspack-grid` class sets up the primary grid structure, while the `newspack-grid--sidebar` class ensures that the single sidebar layout is correctly formatted and displayed. Without these two classes, the layout may not appear as intended. It requires a Columns block with a 2-column layout: 66.66% / 33.33% or 33.33% / 66.66%.
-
-| CLASS NAME             | DESCRIPTION                                  |
-| ---------------------- | -------------------------------------------- |
-| newspack-grid          | The Columns block will use a 12-column grid. |
-| newspack-grid--sidebar | For single sidebar layouts only.             |
-| newspack-grid-small    | The Columns block will use a 6-column grid.  |
-
 # Buttons
 
 Adding `has-small-size` or `has-x-small-size` to a Buttons block will reduce its padding and border-radius.

.github/VARIABLES.md

@@ -85,7 +85,7 @@ _Viewport range for clamp: 782px > 1280px_
 | --wp--preset--color--contrast-3 | #6C6C6C |
 | --wp--preset--color--accent     | #003DA5 |
 | --wp--preset--color--accent-2   | #2055B0 |
-| --wp--preset--color--accent-3   | #26D07C |
+| --wp--preset--color--accent-3   | #9FB6DD |
 
 ## Newspack UI-like
 

.github/workflows/auto-merge.yml

@@ -1,18 +1,38 @@
 on:
   pull_request_target:
-    types: [labeled]
 
 name: Dependabot auto-merge
 jobs:
   auto-merge:
     name: Auto-merge dependabot PRs for minor and patch updates
     runs-on: ubuntu-latest
-    if: |
-      contains( github.event.pull_request.labels.*.name, 'dependencies' )
-      && ! contains( github.event.pull_request.labels.*.name, '[Status] Approved' )
+    if: github.actor == 'dependabot[bot]'
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v2
-      - uses: ahmadnassri/action-dependabot-auto-merge@v2
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
         with:
-          target: minor # includes patch updates.
-          github-token: ${{ secrets.DEPENDABOT_TOKEN }}
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Approve PR
+        if: >-
+          (contains(steps.metadata.outputs.update-type, 'version-update:semver-minor') ||
+          contains(steps.metadata.outputs.update-type, 'version-update:semver-patch')) &&
+          !contains(steps.metadata.outputs.update-type, 'version-update:semver-major')
+        run: gh pr review --approve "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.DEPENDABOT_TOKEN }}
+
+      - name: Enable auto-merge for minor and patch updates
+        if: >-
+          (contains(steps.metadata.outputs.update-type, 'version-update:semver-minor') ||
+          contains(steps.metadata.outputs.update-type, 'version-update:semver-patch')) &&
+          !contains(steps.metadata.outputs.update-type, 'version-update:semver-major')
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.DEPENDABOT_TOKEN }}

AGENTS.md

@@ -0,0 +1,23 @@
+# Newspack Block Theme: Agent Instructions
+
+This file covers what is specific to `newspack-block-theme`. Shared conventions (Docker commands, `n` script, coding standards, git rules, etc.) are in the root `newspack-workspace/AGENTS.md`.
+
+## Overview
+
+`newspack-block-theme` is a WordPress block theme. Templates, template parts, and patterns are HTML files in `templates/`, `parts/`, and `patterns/` respectively. Global styles, layout, typography, and color are controlled via `theme.json`. Two style variations exist in `styles/`: `harold.json` and `paul.json`.
+
+## Blocks
+
+Do not add new blocks to this repo. New blocks should be added to `newspack-plugin` (most cases) or `newspack-blocks`. The existing `includes/blocks/subtitle-block/` is the only block that belongs here as it is tightly coupled to theme-level post metadata.
+
+## Gotchas
+
+- **`npm run lint` skips PHP.** Run `npm run lint:php` separately for PHP linting.
+- **`style.css` and `style-rtl.css` are generated.** They are copied from `dist/` after the webpack build. Edit the SCSS source in `src/scss/`, not the root CSS files.
+- **Nested patterns are not auto-registered by WordPress.** WordPress only auto-registers pattern files at the top level of `/patterns/`. Subdirectory patterns are handled by the recursive `register_nested_patterns()` in `includes/class-patterns.php`, which traverses all depths automatically — no manual registration is needed when adding a new file to a subdirectory. Note that `patterns/plugins/jetpack/` is a two-level-deep subdirectory containing Jetpack sharing button patterns; plugin-specific patterns live there.
+- **Webpack entry points for blocks are auto-discovered.** Any `.js`, `.jsx`, `.ts`, or `.tsx` file in `includes/blocks/*/` becomes an entry point automatically. No changes to `webpack.config.js` are needed.
+- **External patterns are intentionally blocked.** The theme prevents Jetpack, WooCommerce, and Automattic remote patterns from loading. This is by design — do not remove these filters.
+- **After adding a new PHP class file, run `composer dump-autoload`.** The `includes/` directory uses classmap autoloading, not PSR-4.
+- **The Article Subtitle block has two completely different implementations.** In the post editor it is not a block at all — it injects a `contenteditable` div directly into the DOM and updates post meta via `editPost()`. In the site editor it registers normally via `registerBlockType()`. Modifying it requires understanding which context you are in.
+- **There are two separate menu systems with different selectors.** Mobile headers use `.header-mobile` (container), `.mobile-menu__toggle` / `.mobile-menu__contents` (handled by `menus/mobile.js`). Drawer menus used in some desktop header patterns use `.drawer-menu` (container), `.drawer-menu__toggle` / `.drawer-menu__contents` (handled by `menus/drawer.js`). Mixing up the selectors or JS handlers will silently break menu initialization.
+- **Style variations require a unique `className` in their JSON.** The theme reads `wp_get_global_settings()['custom']['className']` and adds it as a `theme-variation-{className}` body class used for CSS scoping. A new style variation in `styles/` must define this value or scoped styles will not apply.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -24,6 +24,22 @@ If you have a patch or have stumbled upon an issue with the Newspack plugin/them
 - Run `npm start` to compile the SCSS and JS files, and start file watcher.
 - Run `npm run build` to perform a single compilation run.
 
+### Theme structure
+
+This is a WordPress block theme. Global styles, layout, typography, and color are defined in `theme.json`. Templates and template parts are HTML block markup files:
+
+- `templates/` — Page templates (front page, single, archive, search, 404, etc.). Some templates have layout variants in subdirectories (e.g. `templates/single/`, `templates/page/`).
+- `parts/` — Reusable template parts (header, footer, menus). Headers and footers have separate mobile and desktop variants (e.g. `parts/header-mobile.html`, `parts/header-desktop.html`).
+- `patterns/` — Block patterns organized into subdirectories by category (header, footer, post-header, post-meta, etc.). Note that patterns in subdirectories are not auto-registered by WordPress and are handled manually in `includes/class-patterns.php`.
+
+### Blocks
+
+This theme contains one custom block (`includes/blocks/subtitle-block/`) which is tightly coupled to theme-level post metadata. New blocks should not be added here — they belong in `newspack-plugin` (most cases) or `newspack-blocks`.
+
+### Style variations
+
+Two style variations are available in `styles/`: `harold.json` and `paul.json`. Each is a partial `theme.json` that overrides colors and typography from the base theme. Style variations can be selected from Appearance > Design in wp-admin.
+
 ### Variables
 
 A cheat sheet of the most important CSS variables is available [here](https://github.com/Automattic/newspack-block-theme/blob/trunk/.github/VARIABLES.md).

assets/fonts/dm-sans/DMSans-Italic-VariableFont_opsz,wght.ttf

@@ -0,0 +1,93 @@
+Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.