8000 fix(core): keep the reveal when `when` changes from true to null by morellodev · Pull Request #336 · awesome-reveal/awesome-reveal · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/rules/core/adapter-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ paths:
- Start `play` in the same task that removes `data-awesome-reveal`. Between the two, the element shows at full opacity, because `fill: "backwards"` applies the first keyframe only after `play` creates the animation.
- Hide in this order: cancel the animation, then tell the listener. Reveal in this order, in the same task: tell the listener, remove `data-awesome-reveal`, `play`, then call `onReveal`.
- `setOptions` replaces the options and does not merge them. Only a change of `when` or `threshold` restarts the observer. `createReveal` copies the options, because a directive can pass the same mutated object again.
- `when == null` means that the viewport decides. Use `??` and `== null`, not default values, because defaults do not apply to `null`.
- `when == null` means that the viewport decides. A change from `true` to `null` keeps the reveal, with no second entrance and no second `onReveal`. Use `??` and `== null`, not default values, because defaults do not apply to `null`.
- A revealed state plays once. `revealed` starts `false`, also with `when: true`, so that the server renders the element hidden. The first `attach` reveals and plays the entrance. A new element keeps the state and does not play again. The same element attached again right after `attach(null)` plays again only when `null` cancelled a running entrance. A finished entrance does not replay, because React Suspense and Activity detach and attach the same element when they hide and show it.
- The behavior spec of the adapters is the contract suite in `packages/test-utils` (`contract.ts`, `contract-ssr.ts`). Change a behavior there first, so that all adapters follow. A framework adapter cannot add behavior that core does not have.
- A cascade store reads the children in `play`, at the reveal, and not at `attach`, so children that the framework renders after the attach also animate. Imperative `cascade()` reads them when it is called. The adapter cascade hides the children, not the container: `[data-awesome-reveal="cascade"] > *`. With a hidden container, its background and border appear with no animation. A child with `display: contents`, such as an Astro island or host, gets no visible entrance.
Expand Down
2 changes: 1 addition & 1 deletion packages/astro/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ For a long list, or a grid that is taller than the viewport, wrap each item in `

### Control the reveal

`when` controls the entrance. `true` plays it, and `false` resets it with no exit animation. Without `when`, the viewport controls it. In a client script, pass the rendered tag to `getReveal`, and set the `when` property of the result.
`when` controls the entrance. `true` plays it, and `false` resets it with no exit animation. Without `when`, the viewport controls it. A change from `true` to `null` keeps the element revealed. In a client script, pass the rendered tag to `getReveal`, and set the `when` property of the result.

`when` does not show or hide content. With `when={false}`, the element is transparent, but screen readers read it and the keyboard can focus it. `inert` does not hide content: it only blocks focus, clicks and assistive technology. To hide content, also set `hidden` on the rendered tag:

Expand Down
2 changes: 1 addition & 1 deletion packages/astro/skills/adding-reveal-animations/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ A cascade schedules all children when its container enters the viewport, so the

The cascade reads the children when the container reveals, so a child that you add later shows with no animation. To cascade words or sentences, wrap each one in an element in the markup. Give inline children `display: inline-block`, because a transform does not apply to an inline box. The cascade does not animate a child with `display: contents`, such as a framework island or the host of a nested `Reveal`. Wrap an island in an element to put it in the cascade. Do not collect deeper descendants to animate them.

Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute to the rendered tag, not to the host, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after the client script attaches. In a client script, pass the rendered tag to `getReveal` from `@awesome-reveal/astro`, then set the `when` property of the result and read its `revealed` property. `getReveal` throws for an element that `Reveal` or `Cascade` did not render. With the `<ClientRouter />`, call it again in an `astro:page-load` listener.
Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport, and a revealed element stays revealed. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute to the rendered tag, not to the host, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after the client script attaches. In a client script, pass the rendered tag to `getReveal` from `@awesome-reveal/astro`, then set the `when` property of the result and read its `revealed` property. `getReveal` throws for an element that `Reveal` or `Cascade` did not render. With the `<ClientRouter />`, call it again in an `astro:page-load` listener.

The rendered tag dispatches a `reveal` event that bubbles, one time for each reveal. The event fires when the reveal starts, not when the entrance ends. It also fires when no entrance plays, such as with reduced motion or focus. After `when: false`, the next reveal fires it again. With reduced motion, `when: false` does not reset the reveal, so the event does not fire again.

Expand Down
2 changes: 1 addition & 1 deletion packages/astro/src/control.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/** Controls the reveal of one element that `Reveal` or `Cascade` rendered. */
export interface RevealControl {
/** Controls the reveal manually, as the `when` prop does. `null` gives the control to the viewport. */
/** Controls the reveal manually, as the `when` prop does. `null` gives the control to the viewport, and a revealed element stays revealed. */
when: boolean | null;
/** Tells if the element is revealed. It stays `false` until the client script attaches the element. */
readonly revealed: boolean;
Expand Down
3 changes: 2 additions & 1 deletion packages/astro/test/browser/element.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,8 @@ describe("getReveal", () => {
reveal.when = null;
expect(host.hasAttribute("when")).toBe(false);
expect(reveal.when).toBeNull();
expect(observers.observerOf(element)).toBeDefined();
expect(reveal.revealed).toBe(true);
expect(observers.observerOf(element)).toBeUndefined();
});

it("plays the entrance again after `when` changes to false and to true in one task", async () => {
Expand Down
2 changes: 1 addition & 1 deletion packages/astro/test/package/dist.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ describe("a static build of a page with the published component", () => {

expect(host).toHaveLength(1);
expect(control).toHaveLength(1);
expect(host[0]!.length).toBeLessThan(5200);
expect(host[0]!.length).toBeLessThan(5225);
expect(control[0]!.length).toBeLessThan(600);
});
});
Expand Down
16 changes: 7 additions & 9 deletions packages/core/src/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import type {

/** Configures a declarative entrance and optional manual control. */
export type RevealOptions = CoreRevealOptions & {
/** Controls the entrance manually. `true` reveals, `false` resets the entrance, and no value or `null` lets the viewport decide. It does not show or hide content. With `false`, the element is transparent, but screen readers read it and the keyboard can focus its controls. To hide content, use `hidden`, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. Reduced motion reveals the element also when `when` is `false`. */
/** Controls the entrance manually. `true` reveals, `false` resets the entrance, and no value or `null` lets the viewport decide. A change from `true` to `null` keeps the element revealed. It does not show or hide content. With `false`, the element is transparent, but screen readers read it and the keyboard can focus its controls. To hide content, use `hidden`, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. Reduced motion reveals the element also when `when` is `false`. */
when?: boolean | null;
/** Runs one time for each reveal, also when no entrance plays, such as with reduced motion or focus. */
onReveal?: (element: Element) => void;
Expand Down Expand Up @@ -98,7 +98,7 @@ function createStore<Options extends CascadeOptions>(
if (preference?.matches && element) {
cancel();
disconnect();
set(true);
set((inView = true));
}
}

Expand Down Expand Up @@ -133,13 +133,11 @@ function createStore<Options extends CascadeOptions>(
function connect() {
disconnect();
disconnect = () => {};
if (preference?.matches && element) return set(true);
if (element && typeof element.animate !== "function") return set(true);
if (current.when != null) {
// No observer watches the element while `when` controls the reveal, so the last report is stale.
inView = false;
return set(current.when);
}
// `when` on an attached element sets `inView`, so a later `null` or `threshold` keeps its result.
if (element && current.when != null) inView = current.when;
if (preference?.matches && element) return set((inView = true));
if (element && typeof element.animate !== "function") return set((inView = true));
if (current.when != null) return set(current.when);
set(inView);
if (element && !inView) disconnect = observe(element, current, () => set((inView = true)));
}
Expand Down
15 changes: 15 additions & 0 deletions packages/core/test/browser/adapter.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,21 @@ describe("createReveal", () => {
expect(observers.live()).toEqual([]);
});

it("observes the next element after when changes from true to null with no element", () => {
const observers = trackObservers();
const animate = trackAnimations();
const [first, second] = paragraphs();
const state = keep(createReveal(options));
state.attach(first);
state.attach(null);
state.setOptions({ ...options, when: true });
state.setOptions({ ...options, when: null });
state.attach(second);
expect(state.revealed).toBe(false);
expect(animate.calls()).toEqual([]);
expect(observers.observerOf(second)).toBe(observers.live()[0]);
});

it("cancels the animation and stops observing when it gets null", async () => {
const observers = trackObservers();
const state = keep(createReveal(options));
Expand Down
2 changes: 1 addition & 1 deletion packages/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Spread `getProps()` on one DOM element. If you have your own `ref`, give it to `

### Control the reveal

`when` controls the entrance from your state. `true` plays it, and `false` resets it with no exit animation. Without `when`, the viewport controls it.
`when` controls the entrance from your state. `true` plays it, and `false` resets it with no exit animation. Without `when`, the viewport controls it. A change from `true` to no value keeps the element revealed.

`when` does not show or hide content. With `when={false}`, the element is transparent, but screen readers read it and the keyboard can focus it. `inert` does not hide content: it only blocks focus, clicks and assistive technology. To hide content, also set `hidden`, or do not render it:

Expand Down
2 changes: 1 addition & 1 deletion packages/react/skills/adding-reveal-animations/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ A cascade schedules all children when its container enters the viewport, so the

The cascade reads the children when the container reveals, so a child that you add later shows with no animation. To cascade words or sentences, wrap each one in an element in the markup. Give inline children `display: inline-block`, because a transform does not apply to an inline box. Do not put a `Reveal` directly inside a `Cascade`, because the two entrances combine. Do not collect deeper descendants to animate them.

Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after hydration.
Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport, and a revealed element stays revealed. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after hydration.

`onReveal` gets the element one time for each reveal, or the container for a cascade. It runs when the reveal starts, not when the entrance ends. It runs also when no entrance plays, such as with reduced motion or focus. After `when: false`, the next reveal calls it again. With reduced motion, `when: false` does not reset the reveal, so `onReveal` does not run again.

Expand Down
4 changes: 2 additions & 2 deletions packages/react/test/package/tree-shaking.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ describe("consumer bundle", () => {

expect(keptExports["core/dist/adapter.js"]).toContain("createReveal");
expect(css).toBeGreaterThan(0);
expect(bytes + css).toBeLessThan(7025);
expect(bytes + css).toBeLessThan(7050);
});

it("keeps no Reveal component for the hook alone", async () => {
const { keptExports, bytes, css } = await bundle("hook-only.js");

expect(keptExports["core/dist/adapter.js"]).toContain("createReveal");
expect(css).toBeGreaterThan(0);
expect(bytes + css).toBeLessThan(6675);
expect(bytes + css).toBeLessThan(6700);
expect(keptExports).not.toHaveProperty("react/dist/Reveal.js");
});
});
47 changes: 46 additions & 1 deletion packages/test-utils/src/contract.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { CascadeOptions } from "@awesome-reveal/core/adapter";

import { easing } from "./entrance-fixtures";
import { createStage, intersect, scrollToTop, settle, showPart } from "./layout";
import { createStage, intersect, scrollIntoView, scrollToTop, settle, showPart } from "./layout";
import { setReducedMotion } from "./reduced-motion";
import { collectReports, collectWindowErrors } from "./reports";
import { expectSame, trackAnimations, trackObservers } from "./spies";
Expand Down Expand Up @@ -394,6 +394,51 @@ export function describeContract(name: string, harness: Harness) {
expect(animate.calls()).toHaveLength(0);
});

it.each([
["below the fold", false],
["in view", true],
])("a change from when: true to null keeps the element revealed %s", async (_, inView) => {
const >
const m = await mount({ when: true, onReveal });
if (inView) scrollIntoView(m.element());
await rerender(m, { when: null, onReveal });
await settle();
expect(shown(m.element())).toBe(true);
expect(observers.observerOf(m.element())).toBeUndefined();
expect(animate.calls()).toHaveLength(1);
expect(onReveal).toHaveBeenCalledOnce();
});

it("a change from when: true to null after reduced motion ends keeps the element revealed", async () => {
await setReducedMotion("reduce");
const m = await mount({ when: true });
await setReducedMotion("no-preference");
await rerender(m, { when: null });
await settle();
expect(shown(m.element())).toBe(true);
expect(observers.observerOf(m.element())).toBeUndefined();
expect(animate.calls()).toHaveLength(0);
});

it.each([
["at mount", true],
["during the session", false],
])(
"an element that reduced motion revealed %s stays revealed after reduced motion ends",
async (_, atMount) => {
if (atMount) await setReducedMotion("reduce");
const m = await mount({ threshold: 0.5 });
if (!atMount) await setReducedMotion("reduce");
await expect.element(m.element()).not.toHaveAttribute("data-awesome-reveal");
await setReducedMotion("no-preference");
await rerender(m, { threshold: 0.2 });
await settle();
expect(shown(m.element())).toBe(true);
expect(observers.observerOf(m.element())).toBeUndefined();
expect(animate.calls()).toHaveLength(0);
},
);

it("a change from when: false to null with focus inside shows the element at once with no entrance", async () => {
const >
const m = await mount({ when: false, onReveal });
Expand Down
2 changes: 1 addition & 1 deletion packages/vue/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ For a long list, a virtualized list, or a grid that is taller than the viewport,

### Control the reveal

`when` controls the entrance from your state. `true` plays it, and `false` resets it with no exit animation. With `null` or no value, the viewport controls it.
`when` controls the entrance from your state. `true` plays it, and `false` resets it with no exit animation. With `null` or no value, the viewport controls it. A change from `true` to `null` keeps the element revealed.

`when` does not show or hide content. With `when: false`, the element is transparent, but screen readers read it and the keyboard can focus it. `inert` does not hide content: it only blocks focus, clicks and assistive technology. To hide content, also set `hidden`, or use `v-if`:

Expand Down
2 changes: 1 addition & 1 deletion packages/vue/skills/adding-reveal-animations/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ A cascade schedules all children when its container enters the viewport, so the

The cascade reads the children when the container reveals, so a child that you add later shows with no animation. To cascade words or sentences, wrap each one in an element in the markup. Give inline children `display: inline-block`, because a transform does not apply to an inline box. Do not put a `Reveal` directly inside a `Cascade`, because the two entrances combine. Do not collect deeper descendants to animate them.

Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after hydration.
Use `when` for manual control: `true` reveals the element and `false` resets the entrance. `null` or `undefined` returns the control to the viewport, and a revealed element stays revealed. `when` does not show or hide content. With `when: false`, the element is transparent, but screen readers still read it, and the keyboard can focus its controls. To hide content, add the `hidden` attribute, or do not render it. `inert` does not hide the element. It only blocks focus, clicks and assistive technology. With `when: true`, the server still renders the element hidden, and the entrance plays after hydration.

The component emits `reveal` with the element, or with the container for a cascade. The directive calls the `onReveal` function of its options with the same element. Both run one time for each reveal, when the reveal starts, not when the entrance ends. They also run when no entrance plays, such as with reduced motion or focus. After `when: false`, the next reveal runs them again. With reduced motion, `when: false` does not reset the reveal, so they do not run again.

Expand Down
Loading
Loading
0