A Flag With an End

Two Mechanisms, One Component

The shared panel supported one docking mechanism, and it had a known defect on one axis: it published an offset variable that hosts consumed as padding, and vertical padding lengthens the document instead of shortening the content area. Lower content stayed where it was and the panel landed on top of it — reachable by scrolling, but covered at rest.

One consumer had never had that problem, because it rendered the panel as a layout sibling of its main area, so the main area genuinely shrank. That is real packing on the vertical axis, and it is something a fixed-position panel structurally cannot do.

The mechanism was taken into the shared component as a second layout mode. Which creates the familiar risk: a component that now supports two ways of doing the same thing, forever.

The Sentence That Prevents That

So it was introduced with its terms stated: this is a migration flag with an end. The old mode stays the default so the consumers still on it are untouched. Consumers move one at a time, each verified in a real browser, because the change alters a layout root. Once the last one has moved, the flag and the old code path both go away.

Three parts, and all three matter. The default preserves current behavior, so introducing the flag breaks nothing. The migration is per-consumer, so it can be paced. And the finish line is stated, so the flag has a defined completion rather than an indefinite existence.

A flag introduced without a stated end becomes a permanent fork that nobody remembers choosing. Two years later it is not a migration aid, it is a configuration option — every consumer has picked one, nobody knows why theirs is that value, and both code paths must be maintained and tested indefinitely. The end condition costs one sentence at introduction and is nearly impossible to add afterward, because by then somebody depends on each side.

Say How Many Are Left

One more detail that does real work: the record states how many consumers remain on the old path. Not a list of who has migrated — a count of who has not.

That number is what keeps the flag visible. A migration with no progress indicator becomes invisible the moment attention moves elsewhere, and invisible migrations do not finish; they become the permanent fork above. A count that somebody could reduce this week is a standing, checkable reminder that this is a temporary state, and it turns "is this done" from a research question into a lookup.

Code

The flag, with its terms in the code where the flag is·typescript

type PanelProps = {
  /**
   * MIGRATION FLAG WITH AN END - not a permanent choice.
   *
   *   "fixed" (default) - the panel is a position:fixed overlay and
   *     publishes --panel-offset-* for the host to consume. On the
   *     vertical axis this does NOT pack: padding-bottom lengthens
   *     the document instead of shortening the content area, so the
   *     panel covers lower content at rest.
   *
   *   "flow" - the panel is a layout SIBLING of the main area, which
   *     therefore genuinely shrinks. Requires the host to be a
   *     full-height flex column whose main area is
   *     `flex: 1; min-height: 0`.
   *
   * PLAN: "fixed" stays the default so consumers still on it are
   * untouched. Consumers migrate one at a time, each verified in a
   * real browser (this changes a layout root). When the last one has
   * moved, THIS PROP AND THE FIXED PATH ARE BOTH DELETED.
   *
   * REMAINING ON "fixed": 9 of 13.        <- the number that keeps
   *                                          this visible. Update it
   *                                          with every migration.
   */
  panelLayout?: "fixed" | "flow";
};


// The mechanism, so the difference is concrete:
//
//   fixed:  <main>            content: 773px, viewport: 981px
//           <panel/>          panel: 420px, position: fixed
//           host CSS: padding-bottom: var(--panel-offset-bottom)
//           -> the document gets LONGER; 152px of the last card
//              sits under the panel at rest.
//
//   flow:   <div class="column">        display: flex; column;
//             <main/>                   flex: 1; min-height: 0
//             <panel/>                  a SIBLING - main shrinks
//           </div>
//           -> the panel publishes no bottom offset at all, because
//              the layout already reserved the space.

Exercise

Inventory the boolean and enum flags in one shared component or service you maintain. For each, determine whether it was introduced as a migration aid or as a permanent option, and whether anybody said so at the time. For the migration ones, add the end condition and the remaining count now — and if you cannot tell which kind a flag is, that is the finding.

Hint

Check whether any consumer has ever changed its value. A flag every consumer sets once at integration and never touches again is almost always a migration flag whose migration was never finished — and the count of consumers on the non-default value is the migration's actual progress.

Two Mechanisms, One Component

The Sentence That Prevents That

Say How Many Are Left

Code

External links

Exercise

Progress

Comments 0