Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(macros/AvailableInWorkers): support more distinct cases #10029

Merged
merged 5 commits into from
Mar 28, 2024
+55 −24
Merged

feat(macros/AvailableInWorkers): support more distinct cases #10029

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eaab1bd
Add support for more worker cases in {{AvailableInWorkers}}
teoli2003 Nov 15, 2023
110ed7d
Add missing full stop
teoli2003 Nov 15, 2023
20061f5
Add support for 'notservicenotwindow'
teoli2003 Nov 16, 2023
b9c41c1
Apply review comments
teoli2003 Nov 20, 2023
c1232e5
Second attempt
teoli2003 Dec 11, 2023
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
76 changes: 54 additions & 22 deletions kumascript/macros/AvailableInWorkers.ejs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,15 @@
//
// Parameters:
//
// $0 - workerType (optional)
// $0 - workerType (optional):
// 'only_dedicated_and_window': only in DedicatedWorker (and in Window)
// 'only_dedicated' only in DedicatedWorker
// 'except_service': all workers but ServiceWorker (and in Window)
// 'except_service_and_window': all workers but ServiceWorker (and no window)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@teoli2003 Isn't this the same as only_dedicated?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, there can be a SharedWorker too: https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker

(At least it is my understanding)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

except_service_and_window = DedicatedWorker + SharedWorker
only_dedicated = DedicatedWorker

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification, so this sounds like except_service_and_window could also be named dedicated_and_shared?

Wouldn't it be easiest to just list the workers in which the feature is available (e.g. dedicated,shared) and display a comma separated list of worker types where the feature is available?

Looking at the screenshots again, I find it confusing that there is "available in Dedicated Web Workers" and "only available in Dedicated Web Workers".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@caugner it sounds like this is hard because we can't easily specify multiple options in a macro. Why don't we just do the same as compat/specs and pull the information from metadata? Then we can make the support explicit:

worker support

  • window
  • dedicated worker
  • shared worker
  • service worker

Then {{AvailableInWorkers}} renders some standard text then "Supported in the following types of workers: [list]". If no metadata specified we could assume "all".

Would that be better?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can get the info from w3c/webref. Nevertheless, there is one caveat the website equivalent for {{AvailableInWorker}}: it is more generic as would really be an {{Availability}} macro. There are many more cases: it would tell us if something is available in Worklet (of all kinds), in RTC's Identity provider, …

I think the mid-term solution would be to ditch {{AvailableInWorker}} for an {{Availability}} macro that we can put everywhere (like {{Specifications}} and {{Compat}}). I didn't do this here as this is a much more significant chunk of work (because there are many more cases, and it has to work with additional ones that can appear in the future, and because we need to obtain the w3c/webref key – again not really difficult but a more significant chunk of work).

That's why I wanted a short-term, more effortless solution (once we have the mid-term solution, a script can be run to update all the pages).

From the two proposals from @caugner:

  • more explicit text (dedicated_and_shared)
  • list of features

I prefer the first one as we don't need to add some parsing (or a loop with many unused cases) to the code. The only caveat is that it won't be compatible with the current arguments (which is why I chose the current keywords), so we need a find and replace PR on the whole MDN once this lands (not difficult).

It is on my todo list to update this PR, hopefully today (but so many things are happening in parallel, so that's not a promise)

Copy link
Contributor

@hamishwillee hamishwillee Dec 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I much prefer my proposal of using metadata. This #10029 (comment) is overly complicated because you're trying to define exceptions.

I'm not sure about "one {{Availability}} macro to rule them all". If we have stuff in metadata I think we can do away with macros altogether at some point.

EDIT PS, though I guess I'd like this in "as is" to never getting agreement :-)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the mid-term, we won't even need metadata as this information is available via w3c/webref, which we already use in some macros. (But that's a significant chunk of work, and we need both some writers to define where and how (=text) to display on the page and non-trivial reviewing of the new macro).

That's why I would prefer this stop-gap first: it is similar to what we do know and doesn't impair the change in the future (a find-and-replace script will be easy to do)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. Then how do we get this in!!!

// 'only_service_and_window': only in ServiceWorker (and in Window)
// 'only_service': only in ServiceWorker
// null: (default) All workers (and Window)
//
// The optional first argument has to be one of the ['notservice'].
//
// {{AvailableInWorkers}}
// {{AvailableInWorkers("notservice")}}
Expand All @@ -21,38 +27,64 @@ const note = mdn.localString({
"ko": "참고:",
"ru": "Примечание:",
"zh-CN": "备注：",
"zh-TW": "備註："
"zh-TW": "備註：",
});

const textDefault = mdn.localString({
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>`,
"zh-CN": `此特性在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 中可用`,
"zh-TW": `此功能可在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 中使用`,
"es": `Esta característica está disponible en <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>`,
"fr": `Cette fonctionnalité est disponible via les <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>`,
"ja": `この機能は <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 内で利用可能です`,
"ko": `이 기능은 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>에서 사용할 수 있습니다`,
"ru": `Эта возможность доступна в <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>`
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>.`,
"zh-CN": `此特性在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 中可用。`,
"zh-TW": `此功能可在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 中使用。`,
"es": `Esta característica está disponible en <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>.`,
"fr": `Cette fonctionnalité est disponible via les <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>.`,
"ja": `この機能は <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a> 内で利用可能です。`,
"ko": `이 기능은 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>에서 사용할 수 있습니다.`,
"ru": `Эта возможность доступна в <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>.`,
});

const textServiceWorkers = mdn.localString({
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>, except for <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Workers</a>`,
"zh-CN": `此特性在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>（不包括 <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Worker</a>）中可用`,
"zh-TW": `此功能可在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>（不包括 <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Worker</a>）中使用`
const textNotService = mdn.localString({
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>, except for <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Workers</a>.`,
"zh-CN": `此特性在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>（不包括 <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Worker</a>）中可用。`,
"zh-TW": `此功能可在 <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Worker</a>（不包括 <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Worker</a>）中使用。`,
});

const textNotServiceNotWindow = mdn.localString({
"en-US": `This feature is only available in <a href="/${locale}/docs/Web/API/Web_Workers_API">Web Workers</a>, except for <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Workers</a>.`,
});

const textDedicated = mdn.localString({
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/DedicatedWorkerGlobalScope">Dedicated Web Workers</a>.`,
});

const textDedicatedOnly = mdn.localString({
"en-US": `This feature is only available in <a href="/${locale}/docs/Web/API/DedicatedWorkerGlobalScope">Dedicated Web Workers</a>.`,
});

const textService = mdn.localString({
"en-US": `This feature is available in <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Workers</a>.`,
});

const textServiceOnly = mdn.localString({
"en-US": `This feature is only available in <a href="/${locale}/docs/Web/API/Service_Worker_API">Service Workers</a>.`,
})

const workerType = $0;
const workerType = $0 || 'default';

let text = "";
const associatedText = {
default: () => textDefault,
only_service: () => textNotService,
except_service_and_window: () => textNotServiceNotWindow,
only_dedicated_and_window: () => textDedicated,
only_dedicated: () => textDedicatedOnly,
only_service_and_window: () => textService,
only_service: () => textServiceOnly,
};

if (workerType === "notservice") {
text = textServiceWorkers;
} else if (workerType) {
if (!associatedText[workerType]) {
throw new Error(`'${workerType}' is not a recognized argument to this macro`);
} else {
text = textDefault;
}

const text = associatedText[workerType]();

%>

<div class="notecard note">
Expand Down