html no longer exported from @milkdown/kit/component

[seangwright]

Initial checklist

• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything (or linked relevant results below)

Affected packages and versions

7.9.0

Link to runnable example

No response

Steps to reproduce

1. Use import { html } from "@milkdown/kit/component";
2. Customize some of the rendering with the html function

featureConfigs: {
  "code-mirror": {
    languages: getCodeMirrorLanguages(),
    renderLanguage: (language, selected) => {
      const displayName =
        language.toLowerCase() === "csharp" ? "C#" : language;

      return html`
        <li
          class="language-list-item"
          role="listitem"
          tabindex="0"
          aria-selected="${selected ? "true" : "false"}"
          data-language="${language}"
        >
          ${displayName} ${selected ? "✅" : ""}
        </li>
      `;
    },
  },
},

Expected behavior

I would expect that import { html } from "@milkdown/kit/component"; would continue to work for a minor release, or the migration path to the current release would be documented somewhere.

The CHANGELOG for v7.9.0 states it's a minor version. It also shows major breaking changes. Public APIs have been changed.

1. Does this mean we should expect minor changes in Milkdown's future updates to also include breaking changes?
2. If so, what does "minor" mean? How is this different from "major"?

Actual behavior

You'll get something like ... does not provide an export named 'html' in the build output because this API has been moved.

I updated my customization of renderLanguage to the sample below, but there was 0 documentation that this would be required.

renderLanguage: (language, selected) => {
  const displayName =
    language.toLowerCase() === "csharp" ? "C#" : language;

  return `${displayName} ${selected ? "✅" : ""}`;
},

All that said, I wouldn't need to customize renderLanguage if LanguageDescription could accept a custom displayName.

LanguageDescription.of({
      name: "CSharp",
      displayName: "C#",
      alias: ["csharp", "cs"],
      extensions: ["cs"],
      load() {
        return import("@codemirror/legacy-modes/mode/clike").then((m) =>
          legacy(m.csharp),
        );
      },
    })

This would allow me to display C# in the code menu drop down but render language-csharp which is the name required by Prism.

Runtime

Chrome

OS

Windows

Build and bundle tools

Vite

[Saul-Mirone]

Hi, Thanks for reporting this. I didn't follow the semver because of the same reasons mentioned in this article:

If a package releases a new major version v2.0.0, your package manager won’t install it if your specified range is ^1.2.3. This prevents unexpected breaking changes from affecting your project until you manually update the version range.

In the past versions of milkdown. The v6 to v7 is a major porject level change becuase we've migrated to a headless editor framework and introduced the crepe editor. So I hoped v8 can be that kind of big announcement. And the update in v7.9.0 is a major technical upgrade. I replacted the atomico framework with vue (becuase atomico has zero update in the past whole year, I thought they gave up the project).

But your opionions are really valuable and reminds me that users expect the project to follow semver. So I'll reconsider how can I make it possible to have something like a epoch version, and still following the semver control.

[seangwright]

Thanks for the context!

I understand your need to make changes so that your dependencies stay up to date and that can cause breaking changes for library users. That's not an issue.

It's more the minor version breaking change and lack of docs (and an explanation like this one you just shared) that caught me off guard.

I love the library and appreciate all the work you've shared. Thanks again!